Merge branch 'assets-docs' into linker

docs/client/api.html

@@ -2945,6 +2945,25 @@ by spammers.)
                 'This is a test of Email.send.');
 
 {{/better_markdown}}
+
+<h2 id="assets"><span>Assets</span></h2>
+
+{{#better_markdown}}
+`Assets` allows server code in a Meteor application to access static server
+assets, which are located in the `private` subdirectory of an application's
+tree.
+
+{{> api_box assets_getText }}
+{{> api_box assets_getBinary }}
+
+Static server assets are included by placing them in the application's `private`
+subdirectory. For example, if an application's `private` subdirectory includes a
+directory called `nested` with a file called `data.txt` inside it, then server
+code can read `data.txt` by running:
+
+    var data = Assets.getText('nested/data.txt');
+{{/better_markdown}}
+
 </template>
 
 

docs/client/api.js

@@ -1811,3 +1811,43 @@ Template.api.email_send = {
     }
   ]
 };
+
+Template.api.assets_getText = {
+  id: "assets_getText",
+  name: "Assets.getText(assetPath, [asyncCallback])",
+  locus: "Server",
+  descr: ["Retrieve the contents of the static server asset as a UTF8-encoded string."],
+  args: [
+    {name: "assetPath",
+     type: "String",
+     descr: "The path of the asset, relative to the application's " +
+     "`private` subdirectory."
+    },
+    {name: "asyncCallback",
+     type: "Function",
+     descr: "Optional callback, which is called asynchronously with the error " +
+     "or result after the function is complete. If not provided, the function " +
+     "runs synchronously."
+    }
+  ]
+};
+
+Template.api.assets_getBinary = {
+  id: "assets_getBinary",
+  name: "Assets.getBinary(assetPath, [asyncCallback])",
+  locus: "Server",
+  descr: ["Retrieve the contents of the static server asset as an EJSON Binary."],
+  args: [
+    {name: "assetPath",
+     type: "String",
+     descr: "The path of the asset, relative to the application's " +
+     "`private` subdirectory."
+    },
+    {name: "asyncCallback",
+     type: "Function",
+     descr: "Optional callback, which is called asynchronously with the error " +
+     "or result after the function is complete. If not provided, the function " +
+     "runs synchronously."
+    }
+  ]
+};

docs/client/concepts.html

@@ -28,17 +28,23 @@ CSS rules, and static assets.  Meteor automates the packaging and transmission
 of these different components.  And, it is quite flexible about how you choose
 to structure those components in your file tree.
 
-The only server asset is JavaScript.  Meteor gathers all your JavaScript
-files, excluding anything under the `client`
-and `public` subdirectories, and loads them into a Node.js
+The only server assets are JavaScript and files in the `private` subdirectory.
+Meteor gathers all your JavaScript
+files, excluding anything under the `client`, `public`, and `private`
+subdirectories, and loads them into a Node.js
 server instance inside a fiber.  In Meteor, your server code runs in
 a single thread per request, not in the asynchronous callback style
 typical of Node.  We find the linear execution model a better fit for
 the typical server code in a Meteor application.
 
+Meteor gathers any files under the `private` subdirectory and makes the contents
+of these files available to server code via the [`Assets`](#assets) API. The
+`private` subdirectory is the place for any files that should be accessible to
+server code but not served to the client, like private data files.
+
 There are more assets to consider on the client side.  Meteor
-gathers all JavaScript files in your tree with the exception of
-the `server` and `public` subdirectories for the
+gathers all JavaScript files in your tree, with the exception of
+the `server`, `public`, and `private` subdirectories, for the
 client.  It minifies this bundle and serves it to each new client.
 You're free to use a single JavaScript file for your entire application, or
 create a nested tree of separate files, or anything in between.
@@ -61,8 +67,8 @@ containing passwords or authentication mechanisms, should be
 kept in the `server` directory.
 
 CSS files are gathered together as well: the client will get a bundle with all
-the CSS in your tree (excluding the `server`
-and `public` subdirectories).
+the CSS in your tree (excluding the `server`,
+`public`, and `private` subdirectories).
 
 In development mode, JavaScript and CSS files are sent individually to make
 debugging easier.

docs/client/docs.js

@@ -314,6 +314,10 @@ var toc = [
     ],
     "Email", [
       "Email.send"
+    ],
+    {name: "Assets", id: "assets"}, [
+      {name: "Assets.getText", id: "assets_getText"},
+      {name: "Assets.getBinary", id: "assets_getBinary"}
     ]
   ],