Merge branch 'devel' into helper-syntax

docs/.meteor/versions

@@ -28,6 +28,7 @@ json@1.0.0
 less@1.0.8
 livedata@1.0.9
 logging@1.0.3
+markdown@1.0.1
 meteor-platform@1.1.0
 meteor@1.1.0
 minifiers@1.1.0

docs/client/api.html

@@ -3578,6 +3578,9 @@ package is exported to.
 {{> autoApiBox "PackageAPI#export" }}
 {{> autoApiBox "PackageAPI#addFiles" }}
 
+{{> autoApiBox "Package.registerBuildPlugin"}}
+{{> autoApiBox "Plugin.registerSourceHandler"}}
+
 <h3 id="packagetests"><span>Unit Tests</span></h3>
 
 {{#markdown}}

docs/client/docs.js

@@ -385,20 +385,19 @@ var toc = [
       {name: "Package.onTest", id: "packagetests"},
       {name: "Npm.depends", id: "Npm-depends"},
       {name: "Npm.require", id: "Npm-require"},
-      {name: "Cordova.depends", id: "Cordova-depends"}
+      {name: "Cordova.depends", id: "Cordova-depends"},
+      {name: "Package.registerBuildPlugin", id: "Package-registerBuildPlugin"}, [
+        {name: "Plugin.registerSourceHandler", id: "Plugin-registerSourceHandler"}
+      ]
     ]
   ],
 
   "Packages", [ [
     "accounts-ui",
-    "amplify",
     "appcache",
     "audit-argument-checks",
-    "backbone",
-    "bootstrap",
     "browser-policy",
     "coffeescript",
-    "d3",
     "fastclick",
     "force-ssl",
     "jquery",

docs/client/names.json

@@ -45,6 +45,22 @@
   "Blaze.renderWithData",
   "Blaze.toHTML",
   "Blaze.toHTMLWithData",
+  "CompileStep",
+  "CompileStep#addAsset",
+  "CompileStep#addHtml",
+  "CompileStep#addJavaScript",
+  "CompileStep#addStylesheet",
+  "CompileStep#arch",
+  "CompileStep#declaredExports",
+  "CompileStep#error",
+  "CompileStep#fileOptions",
+  "CompileStep#fullInputPath",
+  "CompileStep#inputPath",
+  "CompileStep#inputSize",
+  "CompileStep#packageName",
+  "CompileStep#pathForSourceMap",
+  "CompileStep#read",
+  "CompileStep#rootOutputPath",
   "Cordova",
   "Cordova.depends",
   "DDP.connect",
@@ -132,12 +148,15 @@
   "Package.describe",
   "Package.onTest",
   "Package.onUse",
+  "Package.registerBuildPlugin",
   "PackageAPI",
   "PackageAPI#addFiles",
   "PackageAPI#export",
   "PackageAPI#imply",
   "PackageAPI#use",
   "PackageAPI#versionsFrom",
+  "Plugin",
+  "Plugin.registerSourceHandler",
   "ReactiveVar",
   "ReactiveVar#get",
   "ReactiveVar#set",

docs/client/packages.html

@@ -19,14 +19,10 @@ and removed with:
 Meteor Development Group maintains the following packages:
 
 {{> pkg_accounts_ui}}
-{{> pkg_amplify}}
 {{> pkg_appcache}}
 {{> pkg_audit_argument_checks}}
-{{> pkg_backbone}}
-{{> pkg_bootstrap}}
 {{> pkg_browser_policy}}
 {{> pkg_coffeescript}}
-{{> pkg_d3}}
 {{> pkg_fastclick}}
 {{> pkg_force_ssl}}
 {{> pkg_jquery}}

docs/client/packages/amplify.html

@@ -1,14 +0,0 @@
-<template name="pkg_amplify">
-{{#markdown}}
-
-## `amplify`
-
-[Amplify](http://amplifyjs.com/) provides a simple cross-browser API for HTML5 local storage, an
-in-browser communication channel for loosely coupling application
-components, and several useful utility functions.
-
-Amplify defines a global namespace `amplify` on the client only. It does
-not run on the server.
-
-{{/markdown}}
-</template>

docs/client/packages/backbone.html

@@ -1,11 +0,0 @@
-<template name="pkg_backbone">
-{{#markdown}}
-## `backbone`
-
-[Backbone](http://documentcloud.github.com/backbone/) is a popular client-side MVC framework for managing complex
-data in the browser. In addition to the MVC and DOM-binding
-functionality, it also provides an API for HTML5 pushState and
-client-side URL routing.
-
-{{/markdown}}
-</template>

docs/client/packages/bootstrap.html

@@ -1,13 +0,0 @@
-<template name="pkg_bootstrap">
-{{#markdown}}
-## `bootstrap`
-
-[Twitter's Bootstrap](http://twitter.github.com/bootstrap/) package is a front-end toolkit for faster, more
-beautiful web development.  Bootstrap provides simple and flexible HTML,
-CSS, and JavaScript for popular user interface components and
-interactions including typography, forms, buttons, tables, grids, and
-navigation.
-
-
-{{/markdown}}
-</template>

docs/client/packages/d3.html

@@ -1,17 +0,0 @@
-<template name="pkg_d3">
-{{#markdown}}
-
-## `d3`
-
-[D3.js](http://d3js.org/) is a JavaScript library for manipulating
-documents based on data. D3 helps you bring data to life using HTML, SVG
-and CSS. D3's emphasis on web standards gives you the full capabilities
-of modern browsers without tying yourself to a proprietary framework,
-combining powerful visualization components and a data-driven approach
-to DOM manipulation.
-
-The `d3` package adds the D3 library to the client JavaScript
-bundle. It has no effect on the server.
-
-{{/markdown}}
-</template>

packages/deprecated/README

@@ -0,0 +1,6 @@
+These packages are no longer actively maintained by MDG.  Seek
+community alternatives instead.
+
+Note that these packages still exist in atmosphere, and you can still
+build a package that depends on one of them by specifying an explicit
+package version.

packages/markdown/.gitignore

@@ -0,0 +1 @@
+.build*

packages/markdown/package.js

@@ -0,0 +1,18 @@
+// Source: https://github.com/coreyti/showdown
+
+Package.describe({
+  summary: "Markdown-to-HTML processor",
+  version: "1.0.1"
+});
+
+Package.on_use(function (api) {
+  api.add_files("showdown.js");
+  api.export('Showdown');
+
+  api.use("templating", "client", {weak: true});
+  api.add_files('template-integration.js', 'client');
+});
+
+Package.on_test(function (api) {
+  api.use("blaze", "client");
+});

packages/showdown/package.js

@@ -1,20 +1,8 @@
-// Source: https://github.com/coreyti/showdown
-
-// XXX rename to 'markdown' and credit showdown some other way?
-
 Package.describe({
-  summary: "Markdown-to-HTML processor",
-  version: "1.0.1"
+  summary: "Moved to the 'markdown' package",
+  version: '1.0.1'
 });
 
 Package.on_use(function (api) {
-  api.add_files("showdown.js");
-  api.export('Showdown');
-
-  api.use("templating", "client", {weak: true});
-  api.add_files('template-integration.js', 'client');
-});
-
-Package.on_test(function (api) {
-  api.use("blaze", "client");
+  api.imply("markdown");
 });

packages/spacebars-tests/template_tests.js

@@ -727,7 +727,6 @@ Tinytest.add("spacebars-tests - template_tests - select tags", function (test) {
   options.update({}, {$set: {selected: false}}, {multi: true});
   Tracker.flush();
   options.update({}, {$set: {selected: true}}, {multi: true});
-  window.avital = true;
   Tracker.flush();
   test.equal($(selectEl).find('option')[0].selected, true);
   test.equal($(selectEl).find('option')[1].selected, true);

tools/compiler.js

@@ -578,25 +578,121 @@ var compileUnibuild = function (unipkg, inputSourceArch, packageLoader,
     // way to return errors (that could go in an overall list of
     // errors experienced across all files)
     var readOffset = 0;
+
+    /**
+     * The comments for this class aren't used to generate docs right now.
+     * The docs live in the GitHub Wiki at: https://github.com/meteor/meteor/wiki/CompileStep-API-for-Build-Plugin-Source-Handlers
+     * @class CompileStep
+     * @summary The object passed into Plugin.registerSourceHandler
+     * @global
+     */
     var compileStep = {
+
+      /**
+       * @summary The total number of bytes in the input file.
+       * @memberOf CompileStep
+       * @instance
+       * @type {Integer}
+       */
       inputSize: contents.length,
+
+      /**
+       * @summary The filename and relative path of the input file.
+       * Please don't use this filename to read the file from disk, instead
+       * use [compileStep.read](CompileStep-read).
+       * @type {String}
+       * @instance
+       * @memberOf CompileStep
+       */
       inputPath: relPath,
+
+      /**
+       * @summary The filename and absolute path of the input file.
+       * Please don't use this filename to read the file from disk, instead
+       * use [compileStep.read](CompileStep-read).
+       * @type {String}
+       * @instance
+       * @memberOf CompileStep
+       */
+      fullInputPath: absPath,
+
+      // The below is used in the less and stylus packages... so it should be
+      // public API.
       _fullInputPath: absPath, // avoid, see above..
+
       // XXX duplicates _pathForSourceMap() in linker
-      pathForSourceMap: (
-        inputSourceArch.pkg.name
-          ? inputSourceArch.pkg.name + "/" + relPath
-          : path.basename(relPath)),
+      /**
+       * @summary If you are generating a sourcemap for the compiled file, use
+       * this path for the original file in the sourcemap.
+       * @type {String}
+       * @memberOf CompileStep
+       * @instance
+       */
+      pathForSourceMap: (inputSourceArch.pkg.name ?
+        inputSourceArch.pkg.name + "/" + relPath : path.basename(relPath)),
+
       // null if this is an app. intended to be used for the sources
       // dictionary for source maps.
+      /**
+       * @summary The name of the package in which the file being built exists.
+       * @type {String}
+       * @memberOf CompileStep
+       * @instance
+       */
       packageName: inputSourceArch.pkg.name,
+
+      /**
+       * @summary On web targets, this will be the root URL prepended
+       * to the paths you pick for your output files. For example,
+       * it could be "/packages/my-package".
+       * @type {String}
+       * @memberOf CompileStep
+       * @instance
+       */
       rootOutputPath: inputSourceArch.pkg.serveRoot,
-      arch: inputSourceArch.arch, // XXX: what is the story with arch?
+
+      /**
+       * @summary The architecture for which we are building. Can be "os",
+       * "web.browser", or "web.cordova".
+       * @type {String}
+       * @memberOf CompileStep
+       * @instance
+       */
+      arch: inputSourceArch.arch,
+
+      /**
+       * @deprecated in 0.9.4
+       * This is a duplicate API of the above, we don't need it.
+       */
       archMatches: function (pattern) {
         return archinfo.matches(inputSourceArch.arch, pattern);
       },
+
+      /**
+       * @summary Any options passed to "api.addFiles".
+       * @type {Object}
+       * @memberOf CompileStep
+       * @instance
+       */
       fileOptions: fileOptions,
+
+      /**
+       * @summary The list of exports that the current package has defined.
+       * Can be used to treat those symbols differently during compilation.
+       * @type {Object}
+       * @memberOf CompileStep
+       * @instance
+       */
       declaredExports: _.pluck(inputSourceArch.declaredExports, 'name'),
+
+      /**
+       * @summary Read from the input file. If `n` is specified, returns the
+       * next `n` bytes of the file as a Buffer. XXX not sure if this actually
+       * returns a String sometimes...
+       * @param  {Integer} [n] The number of bytes to return.
+       * @instance
+       * @memberOf CompileStep
+       */
       read: function (n) {
         if (n === undefined || readOffset + n > contents.length)
           n = contents.length - readOffset;
@@ -604,7 +700,18 @@ var compileUnibuild = function (unipkg, inputSourceArch, packageLoader,
         readOffset += n;
         return ret;
       },
-      appendDocument: function (options) {
+
+      /**
+       * @summary Works in web targets only. Add markup to the `head` or `body`
+       * section of the document. 
+       * @param  {Object} options
+       * @param {String} options.section Which section of the document should
+       * be appended to. Can only be "head" or "body".
+       * @param {String} options.data The content to append.
+       * @memberOf CompileStep
+       * @instance
+       */
+      addHtml: function (options) {
         if (! archinfo.matches(inputSourceArch.arch, "web"))
           throw new Error("Document sections can only be emitted to " +
                           "web targets");
@@ -617,6 +724,26 @@ var compileUnibuild = function (unipkg, inputSourceArch, packageLoader,
           data: new Buffer(options.data, 'utf8')
         });
       },
+
+      /**
+       * @deprecated in 0.9.4
+       */
+      appendDocument: function (options) {
+        this.addHtml(options);
+      },
+
+      /**
+       * @summary Web targets only. Add a stylesheet to the document.
+       * @param {Object} options
+       * @param {String} path The requested path for the added CSS, may not be
+       * satisfied if there are path conflicts.
+       * @param {String} data The content of the stylesheet that should be
+       * added.
+       * @param {String} sourceMap A stringified JSON sourcemap, in case the
+       * stylesheet was generated from a different file.
+       * @memberOf CompileStep
+       * @instance
+       */
       addStylesheet: function (options) {
         if (! archinfo.matches(inputSourceArch.arch, "web"))
           throw new Error("Stylesheets can only be emitted to " +
@@ -631,6 +758,22 @@ var compileUnibuild = function (unipkg, inputSourceArch, packageLoader,
           sourceMap: options.sourceMap
         });
       },
+
+      /**
+       * @summary Add JavaScript code. The code added will only see the
+       * namespaces imported by this package as runtime dependencies using
+       * ['api.use'](#PackageAPI-use). If the file being compiled was added
+       * with the bare flag, the resulting JavaScript won't be wrapped in a
+       * closure.
+       * @param {Object} options
+       * @param {String} options.path The path at which the JavaScript file
+       * should be inserted, may not be honored in case of path conflicts.
+       * @param {String} options.data The code to be added.
+       * @param {String} options.sourcePath The path that will be used in
+       * any error messages generated by this file, e.g. `foo.js:4:1: error`.
+       * @memberOf CompileStep
+       * @instance
+       */
       addJavaScript: function (options) {
         if (typeof options.data !== "string")
           throw new Error("'data' option to addJavaScript must be a string");
@@ -642,15 +785,45 @@ var compileUnibuild = function (unipkg, inputSourceArch, packageLoader,
           source: options.data,
           sourcePath: options.sourcePath,
           servePath: path.join(inputSourceArch.pkg.serveRoot, options.path),
-          bare: !! options.bare,
+          bare: !! fileOptions.bare,
           sourceMap: options.sourceMap
         });
       },
+
+      /**
+       * @summary Add a file to serve as-is to the browser or to include on
+       * the browser, depending on the target. On the web, it will be served
+       * at the exact path requested. For server targets, it can be retrieved
+       * using `Assets.getText` or `Assets.getBinary`.
+       * @param {Object} options
+       * @param {String} path The path at which to serve the asset.
+       * @param {Buffer|String} data The data that should be placed in
+       * the file.
+       * @memberOf CompileStep
+       * @instance
+       */
       addAsset: function (options) {
-        if (! (options.data instanceof Buffer))
-          throw new Error("'data' option to addAsset must be a Buffer");
+        if (! (options.data instanceof Buffer)) {
+          if (_.isString(options.data)) {
+            options.data = new Buffer(options.data);
+          } else {
+            throw new Error("'data' option to addAsset must be a Buffer or String.");
+          }
+        }
+        
         addAsset(options.data, options.path);
       },
+
+      /**
+       * @summary Display a build error.
+       * @param  {Object} options
+       * @param {String} message The error message to display.
+       * @param {String} [sourcePath] The path to display in the error message.
+       * @param {Integer} line The line number to display in the error message.
+       * @param {String} func The function name to display in the error message.
+       * @memberOf CompileStep
+       * @instance
+       */
       error: function (options) {
         buildmessage.error(options.message || ("error building " + relPath), {
           file: options.sourcePath,

tools/deploy.js

@@ -400,6 +400,14 @@ var bundleAndDeploy = function (options) {
   if (! messages.hasMessages()) {
     var bundler = require('./bundler.js');
 
+    var bundleResult = bundler.bundle({
+      outputPath: bundlePath,
+      buildOptions: options.buildOptions
+    });
+
+    if (bundleResult.errors)
+      messages.merge(bundleResult.errors);
+
     if (options.recordPackageUsage) {
       var statsMessages = buildmessage.capture({ title: 'Reporting statistics' }, function () {
         stats.recordPackages("sdk.deploy", site);
@@ -411,13 +419,6 @@ var bundleAndDeploy = function (options) {
       }
     }
 
-    var bundleResult = bundler.bundle({
-      outputPath: bundlePath,
-      buildOptions: options.buildOptions
-    });
-
-    if (bundleResult.errors)
-      messages.merge(bundleResult.errors);
   }
 
   if (messages.hasMessages()) {

tools/package-source.js

@@ -587,7 +587,27 @@ _.extend(PackageSource.prototype, {
       // - sources: sources for the plugin (array of string)
       // - npmDependencies: map from npm package name to required
       //   version (string)
-      _transitional_registerBuildPlugin: function (options) {
+      
+      /**
+       * @summary Define a build plugin. A build plugin extends the build
+       * process for apps and packages that use this package. For example,
+       * the `coffeescript` package uses a build plugin to compile CoffeeScript
+       * source files into JavaScript.
+       * @param  {Object} [options]
+       * @param {String} options.name A cosmetic name, must be unique in the
+       * package.
+       * @param {String|String[]} options.use Meteor packages that this
+       * plugin uses, independent of the packages specified in
+       * [api.onUse](#PackageAPI-onUse).
+       * @param {String[]} options.sources The source files that make up the
+       * build plugin, independent from [api.addFiles](#PackageAPI-addFiles).
+       * @param {Object} options.npmDependencies An object where the keys
+       * are NPM package names, and the keys are the version numbers of
+       * required NPM packages, just like in [Npm.depends](#Npm-depends).
+       * @memberOf Package
+       * @locus package.js
+       */
+      registerBuildPlugin: function (options) {
         // Tests don't have plugins; plugins initialized in the control file
         // belong to the package and not to the test. (This will be less
         // confusing in the new control file format).
@@ -620,6 +640,13 @@ _.extend(PackageSource.prototype, {
         self.pluginInfo[options.name] = options;
       },
 
+      /**
+       * @deprecated in 0.9.4
+       */
+      _transitional_registerBuildPlugin: function (options) {
+        this.registerBuildPlugin(options);
+      },
+
       includeTool: function () {
         if (!files.inCheckout()) {
           buildmessage.error("Package.includeTool() can only be used with a " +

tools/unipackage.js

@@ -391,6 +391,11 @@ _.extend(Unipackage.prototype, {
     if (self._pluginsInitialized)
       return;
 
+    /**
+     * @global
+     * @namespace Plugin
+     * @summary The namespace that is exposed inside build plugin files.
+     */
     var Plugin = {
       // 'extension' is a file extension without the separation dot
       // (eg 'js', 'coffee', 'coffee.md')
@@ -401,6 +406,21 @@ _.extend(Unipackage.prototype, {
       //
       // 'handler' is a function that takes a single argument, a
       // CompileStep (#CompileStep)
+      
+      /**
+       * @summary Inside a build plugin source file specified in
+       * [Package.registerBuildPlugin](#Package-registerBuildPlugin),
+       * add a handler to compile files with a certain file extension.
+       * @param  {String} fileExtension The file extension that this plugin
+       * should handle, without the first dot.
+       * Examples: `"coffee"`, `"coffee.md"`.
+       * @param  {Function} handler  A function that takes one argument,
+       * a CompileStep object.
+       *
+       * Documentation for CompileStep is available [on the GitHub Wiki](https://github.com/meteor/meteor/wiki/CompileStep-API-for-Build-Plugin-Source-Handlers).
+       * @memberOf Plugin
+       * @locus Build Plugin
+       */
       registerSourceHandler: function (extension, options, handler) {
         if (!handler) {
           handler = options;