Update README to reflect the change to Gulp.

And restructure the gulp-file a bit to improve readability.

README.md

@@ -1,6 +1,7 @@
 # Paper.js - The Swiss Army Knife of Vector Graphics Scripting
 
-If you want to work with Paper.js, simply download the latest "stable" version from [http://paperjs.org/download/](http://paperjs.org/download/)
+If you want to work with Paper.js, simply download the latest "stable" version
+from [http://paperjs.org/download/](http://paperjs.org/download/)
 
 - Website: <http://paperjs.org/>
 - Discussion forum: <http://groups.google.com/group/paperjs>
@@ -12,39 +13,83 @@ If you want to work with Paper.js, simply download the latest "stable" version f
 
 You can download prebuilt packages from <http://paperjs.org/download/>.
 
-As of July 2013, the recommended way to install and maintain Paper.js is through Bower for browsers, and through NPM for Node.js.
+The recommended way to install and maintain Paper.js as a dependency in your
+project is through Bower for browsers, and through NPM for Node.js.
 
-For OSX see <http://madebyhoundstooth.com/blog/install-node-with-homebrew-on-os-x/> for a tutorial explaining how to install Node.js, NPM and Bower.
+If Bower is already installed installed, simply type this command in your
-
+project folder:
-For Linux see <http://nodejs.org/download/> to locate 32-bit and 64-bit nodejs binaries as well as sources. It is recommended that you download directly from the nodejs site; the version available via many OS-supplied package managers is out-of-date and doesn't work with many of the packages paper uses. NPM is now included with the nodejs distribution. Once nodejs (with npm) has been installed you can install bower using the following command:
-
-    npm install -g bower
-
-With Bower installed, simply type this command in your project folder:
 
     bower install paper
 
-Upon execution, you will find a `paper` folder inside the project's `bower_components` folder. For more information on Bower and to learn about its features for dependence tracking, see <http://bower.io/>.
+Upon execution, you will find a `paper` folder inside the project's
+`bower_components` folder.
 
-## Which Version to Use?
+For more information on how to install Bower, read the chapter [Installing
+Node.js, NPM and Bower](#installing-nodejs-npm-and-bower).
 
-The various distributions come with three different pre-build versions of Paper.js, in minified and normal variants:
+To learn more about its features for dependence tracking, see
+<http://bower.io/>.
 
-- `paper-full.js` – The full version for the browser, including PaperScript support and Acorn.js
+### Which Version to Use?
-- `paper-core.js` – The core version for the browser, without PaperScript support nor Acorn.js. Use this to shave off some bytes when working with JavaScript directly.
-- `paper-node.js` – The version for Node.js. It is recommended to install this through NPM, see below.
 
-## Installing Paper.js for Node.js through NPM
+The various distributions come with three different pre-build versions of
+Paper.js, in minified and normal variants:
 
-You can also use NPM to install Paper.js for Node.js. But before doing so, you need the Cairo Graphics library installed, see <http://cairographics.org/>.
+- `paper-full.js` – The full version for the browser, including PaperScript
+  support and Acorn.js
+- `paper-core.js` – The core version for the browser, without PaperScript
+  support nor Acorn.js. Use this to shave off some bytes when working with
+  JavaScript directly.
+- `paper-node.js` – The version for Node.js. It is recommended to install this
+  through NPM, see below.
 
-**Installing Cairo and Pango on OSX:**
+### Installing Node.js, NPM and Bower
 
-The easiest way to install Cairo is install Homebrew <http://mxcl.github.io/homebrew/> then issue the command:
+Node.js is required by Bower, as well as by Gulp, which needs to be installed if
+you intend to build the library or its documentation by yourself.
+
+There are many tutorials explaining the different ways to install Node.js on
+different platforms. It is generally not recommended to install Node.js through
+OS-supplied package managers, as the its development cycles move fast and these
+versions are often out-of-date.
+
+NVM can be used instead to install and maintain multiple versions of Node.js on
+the same platform, as often required by different projects:
+<http://blog.dynamicprogrammer.com/2014/02/18/installing-node-js-on-mac-osx.html>
+
+on OSX, [Homebrew](http://brew.sh/) is also a good option if one version of
+Node.js on the platform is enough:
+<http://blog.teamtreehouse.com/install-node-js-npm-mac>
+
+Homebrew is recommended on OSX also if you intend to install Paper.js for
+Node.js, as described in the next paragraph.
+
+For Linux see <http://nodejs.org/download/> to locate 32-bit and 64-bit nodejs
+binaries as well as sources, or use NVM: <http://learn.bevry.me/node/install/>
+
+Once Node.js (with NPM) has been installed you can install bower *globally*
+using the following command:
+
+    npm install -g bower
+
+And from there onwards, you should be able to use Bower like this:
+
+    bower search paperjs
+
+### Installing Paper.js for Node.js through NPM
+
+NPM is used to install Paper.js for use in Node.js. But before installing, you
+need the Cairo Graphics library installed, see: <http://cairographics.org/>.
+
+##### Installing Cairo and Pango on OSX:
+
+The easiest way to install Cairo is install Homebrew
+<http://mxcl.github.io/homebrew/> then issue the command:
 
     brew install cairo pango
 
-Note that currently there is an issue on OSX with Cairo. If the above causes errors, the following will most likely fix it:
+Note that currently there is an issue on OSX with Cairo. If the above causes
+errors, the following will most likely fix it:
 
     PKG_CONFIG_PATH=/opt/X11/lib/pkgconfig/ npm install paper
 
@@ -52,15 +97,17 @@ Also, whenever you would like to update the modules, you will need to execute:
 
     PKG_CONFIG_PATH=/opt/X11/lib/pkgconfig/ npm update
 
-**Installing Cairo, Pango and all other dependencies on Debian/Ubuntu Linux:**
+##### Installing Cairo, Pango and all other dependencies on Debian/Ubuntu Linux:
 
-    sudo apt-get install libcairo2-dev libpango1.0-dev libssl-dev libjpeg62-dev libgif-dev
+    sudo apt-get install libcairo2-dev libpango1.0-dev libssl-dev libjpeg62-dev
+    libgif-dev
 
-You might also need to install the build-essential package if you don't usually build from c++ sources:
+You might also need to install the build-essential package if you don't usually
+build from c++ sources:
 
     sudo apt-get install build-essential
 
-**After Cairo has been installed:**
+##### After Cairo has been installed:
 
 You should now be able to install the Paper.js module from NPM:
 
@@ -68,136 +115,201 @@ You should now be able to install the Paper.js module from NPM:
 
 ## Development
 
-**Get the source (for building):**
+The main Paper.js source tree is hosted on
+[GitHub](https://github.com/paperjs/paper.js/). `git` is required to create a
+clone of the repository, and can be easily installed through your preferred
+package manager on your platform.
+
+### Get the Source
 
     git clone --recursive git://github.com/paperjs/paper.js.git
-
-**Get the source (for contributing):**
-
-If you want to contribute to the project you will have to [make a fork](http://help.github.com/forking/). Then do this:
-
-    git clone --recursive git@github.com:yourusername/paper.js.git
     cd paper.js
-    git remote add upstream git://github.com/paperjs/paper.js.git
 
-### Refreshing Your Clone
+To refresh your clone and fetch changes from origin, run:
-
-To fetch changes from origin (your fork), run
 
     git fetch origin
 
-If you are working with a fork and would like to fetch from upstream, run
+To update the `jsdoc-toolkit` submodule, used to generate the documentation,
+run:
 
-    git fetch upstream
+    git submodule update  --init --recursive
-
-To update the `jsdoc-toolkit` submodule inside the `build` folder, used to generate the documentation, run
-
-    git submodule update --init
 
 ### Setting Up For Building
 
-Paper.js has a couple of dependencies as Bower and NPM modules. See <http://madebyhoundstooth.com/blog/install-node-with-homebrew-on-os-x/> for a tutorial explaining how to install Node.js, NPM and Bower on OSX.
+As of 2016, Paper.js uses [Gulp](http://gulpjs.com/) for building, and has a
+couple of dependencies as Bower and NPM modules. Read the chapter [Installing
+Node.js, NPM and Bower](#installing-nodejs-npm-and-bower) if you still need to
+install these.
 
-In order to be able to build Paper.js, after checking out the repository, paper has dependencies that need to be installed. Install them by issuing the following commands from the paper.js directory:
+In order to be able to build Paper.js, after checking out the repository, paper
+has dependencies that need to be installed. Install them by issuing the
+following commands from the Paper.js directory:
 
     npm install
     bower install
 
-You might find that the npm command fails attempting to fetch packages needed for dependencies due to using https (the default protocol to access the npm registry). If that is the case you can switch to using http for registry access with the following command:
+It is also recommended to install Gulp globally, so you can easier execute the
+build commands from anywhere in the command line:
 
-    npm config set registry http://registry.npmjs.org/
+    npm install -g gulp
-
-Next you need to create minified versions of some of these dependencies. This is handled by the `minify-components.sh` script inside the `build` folder:
-
-    cd build
-    ./minify-components.sh
 
 ### Building the Library
 
-The Paper.js sources are distributed across many separate files, organised in subfolders inside the `src` folder. To compile them all into one distributable file, you can run the `build.sh` script inside the `build` folder:
+The Paper.js sources are distributed across many separate files, organised in
+subfolders inside the `src` folder. To compile them all into distributable
+files, you can run the `build` task:
 
-    cd build
+    gulp build
-    ./build.sh
 
-You will then find the built library inside the `dist` folder, named `paper.js`.
+You will then find the built library files inside the `dist` folder, named
-
+`paper-full.js`, `paper-core.js` and `paper-node.js`, along with their minified
-`build.sh` offer two modes:
+versions. Read [Which Version to Use?](#which-version-to-use) for an explanation
-
+of the different versions.
-    commented       Preprocessed but still formated and commented
-    stripped        Formated but without comments (default)
-
-In order to minify the resulting built versions, you can run the `minify.sh` script:
-
-    cd build
-    ./minify.sh
 
 ### Running Directly from Separate Source Files
 
-As a handy alternative to building the library after each change to try it out in your scripts, there is a helper script `src/load.js` that loads the library directly from all the separate source files in the `src` folder. The shell script `load.sh` in the `build` folder produces the `paper-full.js` and `paper-node.js` files in `dist` as symbolic links to `src/load.js`. This means you can switch between loading from sources and loading a built library simply by running `build.sh` or `load.sh` inside the `build` folder.
+As a handy alternative to building the library after each change to try it out
+in your scripts, there is the helper task `load`, that replaces the built
+libraries with symbolic links to the `scrc/load.js` script. This script then
+load the library directly from all the separate source files in the `src`
+folder, through the [Prepro.js](https://github.com/lehni/prepro.js) JavaScript
+preprocessing library.
 
-    cd build
+This means you can switch between loading from sources and loading a built
-    ./load.sh
+library simply by running.
+
+    gulp load
 
 And to go back to a built library
 
-    cd build
+    gulp build
-    ./build.sh
 
-Note that your PaperScripts examples do not need to change, they can keep loading `dist/paper-full.js`, which will always do the right thing. Note also that `src/load.js` handles both browsers and Node.js, through the handy Prepro.js preprocessing library <http://github.com/lehni/prepro.js>.
+Note that your PaperScripts examples do not need to change, they can keep
+loading `dist/paper-full.js`, which will always do the right thing. Note also
+that `src/load.js` handles both browsers and Node.js, as supported by Prepro.js.
+
+### Other Build Tasks
+
+Create a final zipped distribution file inside the `dist` folder:
+
+    gulp dist
+
+And since `dist` is the default task, this is the same:
+
+    gulp
 
 ### Branch structure
 
-Since the release of version `v0.9.22`, Paper.js has adopted aspects of the Git-Flow workflow. For now, this just means that all development is taking place in the `develop` branch, which is only merged into `master` when a new release occurs. On this `develop` branch, `src/load.js` is used by default to load the library.
+Since the release of version `v0.9.22`, Paper.js has adopted aspects of the
-
+Git-Flow workflow. For now, this just means that all development is taking place
+in the `develop` branch, which is only merged into `master` when a new release
+occurs. On this `develop` branch, `src/load.js` is used by default to load the
+library.
 
 ### Building the Documentation
 
-Similarly to building the library, you can run `docs.sh` inside the `build` folder to build the documentation.
+Similarly to building the library, you can run the `docs` task to build the
+documentation:
 
-    cd build
+    gulp docs
-    ./docs.sh
 
 Your docs will then be located at `dist/docs`.
 
 ### Testing
 
-Paper.js was developed and tested from day 1 using proper unit testing through jQuery's [Qunit](http://docs.jquery.com/Qunit). To run the tests after any change to the library's source, simply open `index.html` inside the `test` folder in your web browser. There should be a green bar at the top, meaning all tests have passed. If the bar is red, some tests have not passed. These will be highlighted and become visible when scrolling down.
+Paper.js was developed and tested from day 1 using proper unit testing through
+jQuery's [Qunit](http://docs.jquery.com/Qunit). To run the tests after any
+change to the library's source, simply open `index.html` inside the `test`
+folder in your web browser. There should be a green bar at the top, meaning all
+tests have passed. If the bar is red, some tests have not passed. These will be
+highlighted and become visible when scrolling down.
+
+You can also run the unit tests through Gulp on the command line:
+
+    gulp test
 
 ### Contributing
 
-The main Paper.js source tree is hosted on git (a popular [DVCS](http://en.wikipedia.org/wiki/Distributed_revision_control)), thus you should create a fork of the repository in which you perform development. See <http://help.github.com/forking/>.
+The main Paper.js source tree is hosted on GitHub, thus you should create a fork
+of the repository in which you perform development. See
+<http://help.github.com/forking/>.
 
-We prefer that you send a [*pull request* here on GitHub](http://help.github.com/pull-requests/) which will then be merged into the official main line repository. You need to sign the Paper.js CLA to be able to contribute (see below).
+We prefer that you send a [pull request on GitHub]
+(http://help.github.com/pull-requests/) which will then be merged into the
+official main line repository. You need to sign the Paper.js CLA to be able to
+contribute (see below).
 
-Also, in your first contribution, add yourself to the end of `AUTHORS.md` (which of course is optional).
+Also, in your first contribution, add yourself to the end of `AUTHORS.md` (which
+of course is optional).
+
+**Get the source (for contributing):**
+
+If you want to contribute to the project you will have to [make a
+fork](http://help.github.com/forking/). Then do this:
+
+    git clone --recursive git@github.com:yourusername/paper.js.git
+    cd paper.js
+    git remote add upstream git://github.com/paperjs/paper.js.git
+
+To then fetch changes from upstream, run
+
+    git fetch upstream
 
 #### Creating and Submitting a Patch
 
-As mentioned earlier in this article, we prefer that you send a [*pull request*](http://help.github.com/pull-requests/) on GitHub.
+As mentioned above, we prefer that you send a
+[pull request](http://help.github.com/pull-requests/) on GitHub:
 
-1. Create a fork of the upstream repository by visiting <https://github.com/paperjs/paper.js/fork>. If you feel insecure, here's a great guide: <http://help.github.com/forking/>
+1. Create a fork of the upstream repository by visiting
+   <https://github.com/paperjs/paper.js/fork>. If you feel insecure, here's a
+   great guide: <http://help.github.com/forking/>
 
-2. Clone of your repository: `git clone https://yourusername@github.com/yourusername/paper.js.git`
+2. Clone of your repository: `git clone
+   https://yourusername@github.com/yourusername/paper.js.git`
 
-3. This is important: Create a so-called *topic branch* based on the `develop` branch: `git checkout -tb name-of-my-patch develop` where `name-of-my-patch` is a short but descriptive name of the patch you're about to create. Don't worry about the perfect name though -- you can change this name at any time later on.
+3. This is important: Create a so-called *topic branch* based on the `develop`
+   branch: `git checkout -tb name-of-my-patch develop` where `name-of-my-patch`
+   is a short but descriptive name of the patch you're about to create. Don't
+   worry about the perfect name though -- you can change this name at any time
+   later on.
 
-4. Hack! Make your changes, additions, etc., commit them then push them to your GitHub fork: `git push origin name-of-my-patch`
+4. Hack! Make your changes, additions, etc., commit them then push them to your
+   GitHub fork: `git push origin name-of-my-patch`
 
-5. Send a pull request to the upstream repository's owner by visiting your repository's site at GitHub (i.e. https://github.com/yourusername/paper.js) and press the "Pull Request" button. Make sure you are creating the pull request to the `develop` branch, not the `master` branch. Here's a good guide on pull requests: <http://help.github.com/pull-requests/>
+5. Send a pull request to the upstream repository's owner by visiting your
+   repository's site at GitHub (i.e. https://github.com/yourusername/paper.js)
+   and press the "Pull Request" button. Make sure you are creating the pull
+   request to the `develop` branch, not the `master` branch. Here's a good guide
+   on pull requests: <http://help.github.com/pull-requests/>
 
-**Use one topic branch per feature** -- don't mix different kinds of patches in the same branch. Instead, merge them all together into your `develop` branch (or develop everything in your `develop` branch and then cherry-pick-and-merge into the different topic branches). Git provides for an extremely flexible workflow, which in many ways causes more confusion than it helps you when new to collaborative software development. The guides provided by GitHub at <http://help.github.com/> are a really good starting point and reference.
+##### Use one topic branch per feature:
-If you are fixing an issue, a convenient way to name the branch is to use the issue number as a prefix, like this: `git checkout -tb 53-feature-manually-select-language`.
+
+Don't mix different kinds of patches in the same branch. Instead, merge them all
+together into your `develop` branch (or develop everything in your `develop`
+branch and then cherry-pick-and-merge into the different topic branches). Git
+provides for an extremely flexible workflow, which in many ways causes more
+confusion than it helps you when new to collaborative software development. The
+guides provided by GitHub at <http://help.github.com/> are a really good
+starting point and reference. If you are fixing an issue, a convenient way to
+name the branch is to use the issue number as a prefix, like this: `git checkout
+-tb issue-937-feature-add-text-styling`.
 
 #### Contributor License Agreement
 
-Before we can accept any contributions to Paper.js, you need to sign this [CLA](http://en.wikipedia.org/wiki/Contributor_License_Agreement):
+Before we can accept any contributions to Paper.js, you need to sign this
+[CLA](http://en.wikipedia.org/wiki/Contributor_License_Agreement):
 
 [Contributor License Agreement](https://spreadsheets.google.com/a/paperjs.org/spreadsheet/embeddedform?formkey=dENxd0JBVDY2REo3THVuRmh4YjdWRlE6MQ)
 
-> The purpose of this agreement is to clearly define the terms under which intellectual property has been contributed to Paper.js and thereby allow us to defend the project should there be a legal dispute regarding the software at some future time.
+> The purpose of this agreement is to clearly define the terms under which
+> intellectual property has been contributed to Paper.js and thereby allow us to
+> defend the project should there be a legal dispute regarding the software at
+> some future time.
 
-For a list of contributors, please see [AUTHORS](https://github.com/paperjs/paper.js/blob/master/AUTHORS.md)
+For a list of authors and contributors, please see [AUTHORS]
+(https://github.com/paperjs/paper.js/blob/master/AUTHORS.md).
 
 ## License
 
-Distributed under the MIT license. See [LICENSE.txt](https://github.com/paperjs/paper.js/blob/master/LICENSE.txt) for details.
+Distributed under the MIT license. See [LICENSE]
+(https://github.com/paperjs/paper.js/blob/master/LICENSE.txt) for details.

gulpfile.js

@@ -25,6 +25,10 @@ var gulp = require('gulp'),
     gitty = require('gitty')('.'),
     fs = require('fs');
 
+/**
+ * Options
+ */
+
 // Options to be used in Prepro.js preprocessing through the global __options
 // object.
 var buildOptions = {
@@ -45,21 +49,31 @@ var uglifyOptions = {
     }
 };
 
+var acornPath = 'bower_components/acorn/';
+
 var buildNames = Object.keys(buildOptions);
 var docNames = Object.keys(docOptions);
 
-gulp.task('default', ['dist']);
-
 gulp.on('error', function(err) {
     console.error(err.toString());
     gulp.emit('end');
 });
 
+gulp.task('default', ['dist']);
+
+/**
+ * Task: test
+ */
+
 gulp.task('test', function() {
     return gulp.src('test/index.html')
         .pipe(qunit({ timeout: 20, noGlobals: true }));
 });
 
+/**
+ * Task: docs
+ */
+
 docNames.forEach(function(name) {
     gulp.task('docs:' + name, ['clean:docs'], shell.task([
         'java -cp jsrun.jar:lib/* JsRun app/run.js -c=conf/' + name + '.conf ' +
@@ -78,6 +92,10 @@ gulp.task('clean:docs', function(callback) {
     ]);
 });
 
+/**
+ * Task: load
+ */
+
 gulp.task('load', ['clean:load'], function() {
     return gulp.src('src/load.js')
         .pipe(symlink('dist/paper-full.js'))
@@ -91,50 +109,26 @@ gulp.task('clean:load', function() {
     ]);
 });
 
+/**
+ * Task: build
+ */
+
 gulp.task('build',
     buildNames.map(function(name) {
         return 'build:' + name;
     })
 );
 
-gulp.task('minify', ['build'], function() {
+// Get the date of the last commit from git.
-    return gulp.src([
+var gitLog = gitty.logSync('-1');
-            'dist/paper-full.js',
-            'dist/paper-core.js'
-        ])
-        .pipe(uglify(uglifyOptions))
-        .pipe(rename({
-            suffix: '.min'
-        }))
-        .pipe(gulp.dest('dist'));
-});
-
-gulp.task('dist', ['minify', 'docs'], function() {
-    return merge(
-            gulp.src([
-                'dist/paper-full*.js',
-                'dist/paper-core*.js',
-                'LICENSE.txt',
-                'examples/**/*',
-            ], { base: '.' }),
-            gulp.src([
-                'dist/docs/**/*'
-            ], { base: 'dist' })
-        )
-        .pipe(zip('/paperjs.zip'))
-        .pipe(gulp.dest('dist'));
-});
-
 buildNames.forEach(function(name) {
-    // Get the date of the last commit from git.
-    var logData = gitty.logSync('-1');
     gulp.task('build:' + name, ['build:start'], function() {
         return gulp.src('src/paper.js')
             .pipe(prepro({
                 evaluate: ['src/constants.js', 'src/options.js'],
                 setup: function() {
                     var options = buildOptions[name];
-                    options.date = logData[0].date;
+                    options.date = gitLog[0].date;
                     // This object will be merged into the Prepro.js VM scope,
                     // which already holds a __options object from the above
                     // include statement.
@@ -164,16 +158,51 @@ gulp.task('clean:build', function() {
 });
 
 gulp.task('minify:acorn', function() {
-    var path = 'bower_components/acorn/';
     // Only compress acorn if the compressed file doesn't exist yet.
     try {
-        fs.accessSync(path + 'acorn.min.js');
+        fs.accessSync(acornPath + 'acorn.min.js');
     } catch(e) {
-        return gulp.src(path + 'acorn.js')
+        return gulp.src(acornPath + 'acorn.js')
             .pipe(uglify(uglifyOptions))
             .pipe(rename({
                 suffix: '.min'
             }))
-            .pipe(gulp.dest(path));
+            .pipe(gulp.dest(acornPath));
     }
 });
+
+/**
+ * Task: minify
+ */
+
+gulp.task('minify', ['build'], function() {
+    return gulp.src([
+            'dist/paper-full.js',
+            'dist/paper-core.js'
+        ])
+        .pipe(uglify(uglifyOptions))
+        .pipe(rename({
+            suffix: '.min'
+        }))
+        .pipe(gulp.dest('dist'));
+});
+
+/**
+ * Task: dist
+ */
+
+gulp.task('dist', ['minify', 'docs'], function() {
+    return merge(
+            gulp.src([
+                'dist/paper-full*.js',
+                'dist/paper-core*.js',
+                'LICENSE.txt',
+                'examples/**/*',
+            ], { base: '.' }),
+            gulp.src([
+                'dist/docs/**/*'
+            ], { base: 'dist' })
+        )
+        .pipe(zip('/paperjs.zip'))
+        .pipe(gulp.dest('dist'));
+});