Updated docs, added author, clarified comment

mudivili · Nov 18, 2012 · 58cf94d · 58cf94d
1 parent adde3fd
commit 58cf94d
Show file tree

Hide file tree

Showing 5 changed files with 106 additions and 153 deletions.
diff --git a/AUTHORS b/AUTHORS
@@ -1,2 +1,3 @@
 "Cowboy" Ben Alman (http://benalman.com)
-Tyler Kellen (http://goingslowly.com)
+Tyler Kellen (http://goingslowly.com)
+Jarrod Overson (http://jarrodoverson.com)
diff --git a/docs/uglify-examples.md b/docs/uglify-examples.md
@@ -1,103 +1,68 @@
-## Usage examples
-
-### Minifying individual files
-
-In this example, running `grunt min:dist` (or `grunt min` because `min` is a [multi task](types_of_tasks.md)) will minify the specified source file, writing the output to `dist/built.min.js`.
-
-_Note that UglifyJS strips all comments from the source, including banner comments. See the "Banner comments" example for instructions on how to add a banner to the generated source._
-
-```javascript
-// Project configuration.
-grunt.initConfig({
-  min: {
-    dist: {
-      src: ['dist/built.js'],
-      dest: 'dist/built.min.js'
-    }
-  }
-});
-```
-
-### Minifying while concatenating files
-
-In this example, running `grunt min:dist` (or `grunt min` because `min` is a [multi task](types_of_tasks.md)) will first concatenate the three specified source files, in order, minifying the result and writing the output to `dist/built.min.js`.
-
-_Note that UglifyJS strips all comments from the source, including banner comments. See the "Banner comments" example for instructions on how to add a banner to the generated source._
-
-```javascript
-// Project configuration.
-grunt.initConfig({
-  min: {
-    dist: {
-      src: ['src/intro.js', 'src/project.js', 'src/outro.js'],
-      dest: 'dist/built.min.js'
-    }
-  }
-});
-```
-
-With a slight modification, running `grunt min` will join the specified source files using `;` instead of the default newline character before minification.
-
-```javascript
-// Project configuration.
-grunt.initConfig({
-  min: {
-    dist: {
-      src: ['src/intro.js', 'src/project.js', 'src/outro.js'],
-      dest: 'dist/built.min.js',
-      separator: ';'
-    }
-  }
-});
-```
-
-### Minifying and concatenating separately
-
-Often, it's desirable to create both unminified and minified distribution files. In these cases, the [concat task](task_concat.md) should be run first, followed by the `min` task.
-
-In this example, running `grunt concat:dist min:dist` (or `grunt concat min` because both `concat` and `min` are [multi tasks](types_of_tasks.md)) will first concatenate the three specified source files, in order, writing the output to `dist/built.js`. After that, grunt will minify the newly-created file, writing the output to `dist/built.min.js`.
-
-_Note that UglifyJS strips all comments from the source, including banner comments. See the "Banner comments" example for instructions on how to add a banner to the generated source._
-
-```javascript
-// Project configuration.
-grunt.initConfig({
-  concat: {
-    dist: {
-      src: ['src/intro.js', 'src/project.js', 'src/outro.js'],
-      dest: 'dist/built.js'
-    }
-  },
-  min: {
-    dist: {
-      src: ['dist/built.js'],
-      dest: 'dist/built.min.js'
-    }
-  }
-});
-```
+# Usage examples
+
+### All tasks are specified in an `uglify` block
+
+        uglify: {
+
+### This is a multitask and options specified at the root level will be merged with each task
+
+          options: {
+            mangle : {
+              except : ['jQuery', 'Backbone']
+            }
+          },
+
+### Just use default options to compress your source
+
+          default: {
+            files: {
+              'source.min.js': ['source.js']
+            }
+          },
+
+### Compress your source only, no mangling
+
+          no_mangle: {
+            files: {
+              'source.min.js': ['source.js']
+            },
+            options : {
+              mangle : false
+            }
+          },
+
+### Compress, mangle, and output source map
+
+          sourcemap: {
+            files: {
+              'source.min.js': ['source.js']
+            },
+            options : {
+              source_map : 'sourcemap.js'
+            }
+          },
+
+### Beautify your compressed and mangled source
+
+          beautified: {
+            files: {
+              'source.min.js': ['source.js']
+            },
+            options : {
+              beautify : {
+                max_line_len : 120
+              }
+            }
+          }
 
 ### Banner comments
 
-In this example, running `grunt min:dist` (or `grunt min` because `min` is a [multi task](types_of_tasks.md)) will first strip any preexisting comments from the `src/project.js` file (because that's how UglifyJS works), then concatenate the result with a newly-generated banner comment, writing the output to `dist/built.js`.
-
-This generated banner will be the contents of the `min.options.banner` underscore template string interpolated with the config object. In this case, those properties are the values imported from the `package.json` file (which are available via the `pkg` config property) plus today's date.
-
-_Note: you don't have to use an external JSON file. It's completely valid to create the `pkg` object inline in the config. That being said, if you already have a JSON file, you might as well reference it.
-
-```javascript
-// Project configuration.
-grunt.initConfig({
-  pkg: grunt.file.readJSON('package.json'),
-  min: {
-    options: {
-      banner: '/*! <%= pkg.name %> - v<%= pkg.version %> - ' +
-        '<%= grunt.template.today("yyyy-mm-dd") %> */'
-    },
-    dist: {
-      src: ['dist/built.js'],
-      dest: 'dist/built.min.js'
-    }
-  }
-});
-```
+          banner: {
+            files: {
+              'source.min.js': ['source.js']
+            },
+            options : {
+              banner: '/*! <%= pkg.name %> - v<%= pkg.version %> - ' +
+                      ' *  <%= grunt.template.today("yyyy-mm-dd") %> */'
+            }
+          }
diff --git a/docs/uglify-options.md b/docs/uglify-options.md
@@ -1,26 +1,35 @@
-### Specifying UglifyJS options
-
-In this example, custom UglifyJS `mangle`, `squeeze` and `codegen` options are specified. The listed methods and their expected options are explained in the API section of the [UglifyJS documentation][uglify]:
-
-* The `mangle` object is passed into the `pro.ast_mangle` method.
-* The `squeeze` object is passed into the `pro.ast_squeeze` method.
-* The `codegen` object is passed into the `pro.gen_code` method.
-
-```javascript
-// Project configuration.
-grunt.initConfig({
-  min: {
-    dist: {
-      src: ['dist/built.js'],
-      dest: 'dist/built.min.js'
-    }
-  },
-  uglify: {
-    mangle: {toplevel: true},
-    squeeze: {dead_code: false},
-    codegen: {quote_keys: true}
-  }
-});
-```
-
-See the [min task source](../tasks/min.js) for more information.
+# UglifyJS options
+
+## API Note:
+
+When in doubt, the options mimic the [UglifyJS2 api](http://lisperator.net/uglifyjs/) *except* where the command line API is found to be simpler (e.g. reusing options passed to `mangle_names` and `compute_char_frequency`.
+
+## mangle
+Type: `Boolean`, `Object`  
+Default: `{}`
+
+Turn on or off mangling with default options. If an `Object` is specified, it is passed directly to `ast.mangle_names()` *and* `ast.compute_char_frequency()` (mimicking command line behavior).
+
+## compress
+Type: `Boolean`, `Object`  
+Default: `{}`
+
+Turn on or off source compression with default options. If an `Object` is specified, it is passed directly to `UglifyJS2.Compressor()`.
+
+## beautify
+Type: `Boolean`, `Object`  
+Default: `false`
+
+Turns on beautification of the generated source code. Any extra options passed are merged with the options sent to `UglifyJS2.OutputStream()`.
+
+## source_map
+Type: `string`  
+Default: `undefined`
+
+Specify the sourcemap location to output.
+
+## banner
+Type: `string`
+Default: `undefined`
+
+Specify a banner to prepend to the output source, e.g. license comments.
diff --git a/docs/uglify-overview.md b/docs/uglify-overview.md
@@ -1,26 +1,5 @@
-## About
+## Overview
 
-This task is a [multi task](types_of_tasks.md), meaning that grunt will automatically iterate over all `min` targets if a target is not specified.
+This task is a [multi task](types_of_tasks.md), meaning that grunt will automatically iterate over all `uglify` targets if a target is not specified.
 
-_Need some help getting started with grunt? Visit the [getting started](getting_started.md) page. And if you're creating your own tasks, be sure to check out the [types of tasks](types_of_tasks.md) page as well as the [API documentation](api.md)._
-
-## A Very Important Note
-Your Gruntfile **must** contain this code, once and **only** once. If it doesn't, grunt won't work. For the sake of brevity, this "wrapper" code has been omitted from all examples on this page, but it needs to be there.
-
-```javascript
-module.exports = function(grunt) {
-  // Your grunt code goes in here.
-};
-```
-
-## Project configuration
-
-This example shows a brief overview of the [config](api_config.md) properties used by the `min` task. For a more in-depth explanation, see the usage examples.
-
-```javascript
-// Project configuration.
-grunt.initConfig({
-  // Lists of files to be minified with UglifyJS.
-  min: {}
-});
-```
+grunt-contrib-uglify primarily delegates to [UglifyJS2](https://github.com/mishoo/UglifyJS2), so please consider the [UglifyJS documentation](http://lisperator.net/uglifyjs/) as required reading for advanced configuration.
diff --git a/tasks/lib/uglify.js b/tasks/lib/uglify.js
@@ -65,8 +65,7 @@ exports.init = function(grunt) {
       }
 
       if (options.mangle !== false ) {
-        // Optimize for gzip compression.
-        // compute_char_frequency creates larger source but compresses better
+        // compute_char_frequency optimizes names for compression
         ast.compute_char_frequency(options.mangle);
 
         // Requires previous call to figure_out_scope