Merge pull request mde#138 from mde/update-docs

Update Documentation

README.md

@@ -42,6 +42,10 @@ template(data);
 
 ejs.render(str, data, options);
 // => Rendered HTML string
+
+ejs.renderFile(filename, data, options, function(err, str){
+    // str => Rendered HTML string
+});
 ```
 
 It is also possible to use `ejs.render(dataAndOptions);` where you pass
@@ -53,10 +57,13 @@ Therefore, we do not recommend using this shortcut.
 ## Options
 
   - `cache`           Compiled functions are cached, requires `filename`
-  - `filename`        Used by `cache` to key caches, and for includes
+  - `filename`        The name of the file being rendered. Not required if you 
+    are using `renderFile()`. Used by `cache` to key caches, and for includes.
   - `context`         Function execution context
   - `compileDebug`    When `false` no debug instrumentation is compiled
-  - `client`          Returns standalone compiled function
+  - `client`          When `true`, compiles a function that can be rendered 
+    in the browser without needing to load the EJS Runtime 
+    ([ejs.min.js](https://github.com/mde/ejs/releases/latest)).
   - `delimiter`       Character to use with angle brackets for open/close
   - `debug`           Output generated function body
   - `strict`          When set to `true`, generated function is in strict mode
@@ -67,6 +74,11 @@ Therefore, we do not recommend using this shortcut.
     slurping for all scriptlet tags (it does not strip new lines of tags in
     the middle of a line).
 
+This project uses [JSDoc](http://usejsdoc.org/). For the full public API 
+documentation, clone the repository and run `npm run doc`. This will run JSDoc 
+with the proper options and output the documentation to `out/`. If you want 
+the both the public & private API docs, run `npm run devdoc` instead.
+
 ## Tags
 
   - `<%`              'Scriptlet' tag, for control-flow, no output
@@ -80,9 +92,12 @@ Therefore, we do not recommend using this shortcut.
 ## Includes
 
 Includes either have to be an absolute path, or, if not, are assumed as
-relative to the template with the `include` call. (This requires the
-`filename` option.) For example if you are including `./views/user/show.ejs`
-from `./views/users.ejs` you would use `<%- include('user/show') %>`.
+relative to the template with the `include` call. For example if you are 
+including `./views/user/show.ejs` from `./views/users.ejs` you would 
+use `<%- include('user/show') %>`.
+
+You must specify the `filename` option for the template with the `include` 
+call unless you are using `renderFile()`.
 
 You'll likely want to use the raw output tag (`<%-`) with your include to avoid
 double-escaping the HTML output.
@@ -157,9 +172,44 @@ including headers and footers, like so:
 ## Client-side support
 
 Go to the [Latest Release](https://github.com/mde/ejs/releases/latest), download
-`./ejs.js` or `./ejs.min.js`.
+`./ejs.js` or `./ejs.min.js`. Alternately, you can compile it yourself by cloning 
+the repository and running `jake build` (or `$(npm bin)/jake build` if jake is 
+not installed globally).
+
+Include one of these files on your page, and `ejs` should be available globally.
+
+### Example
+
+```html
+<div id="output"></div>
+<script src="ejs.min.js"></script>
+<script>
+  var people = ['geddy', 'neil', 'alex'],
+      html = ejs.render('<%= people.join(", "); %>', {people: people});
+  // With jQuery:
+  $('#output').html(html);
+  // Vanilla JS:
+  document.getElementById('output').innerHTML = html;
+</script>
+```
 
-Include one of these on your page, and `ejs.render(str)`.
+### Caveats
+
+Most of EJS will work as expected; however, there are a few things to note:
+
+1. Obviously, since you do not have access to the filesystem, `ejs.renderFile()` won't work.
+2. For the same reason, `include`s do not work unless you use an `IncludeCallback`. Here is an example:
+  ```javascript
+  var str = "Hello <%= include('file', {person: 'John'}); %>",
+      fn = ejs.compile(str, {client: true});
+
+  fn(data, null, function(path, d){ // IncludeCallback
+    // path -> 'file'
+    // d -> {person: 'John'}
+    // Put your code here 
+    // Return the contents of file as a string
+  }); // returns rendered string
+  ```
 
 ## Related projects
 

docs/jsdoc/options.jsdoc

@@ -24,15 +24,18 @@
  * line).
  *
  * @property {Boolean} [client=false]
- * Whether or not to compile functions that are to be included in the browser.
- *
+ * Whether or not to compile a {@link ClientFunction} that can be rendered 
+ * in the browser without depending on ejs.js. Otherwise, a {@link TemplateFunction} 
+ * will be compiled.
+ * 
  * @property {EscapeCallback} [escape={@link module:utils.escapeXML}]
  * The escaping function used with `<%=` construct. It is used in rendering
  * and is `.toString()`ed in the generation of client functions.
  *
  * @property {String}  [filename='undefined']
- * The filename of the template. Used in inclusion, caching, and error
- * reporting.
+ * The filename of the template. Required for inclusion and caching unless 
+ * you are using {@link module:ejs.renderFile}. Also used for error reporting.
+ * 
  * @property {String}  [delimiter='%']
  * The delimiter used in template compilation.
  *

docs/syntax.md

@@ -138,13 +138,24 @@ example below. You can trim it using the `-%>` ending tag.
 ##### EJS
 
 ```html
-<p><%# comment %></p>
+<div>
+<%# comment %>
+</div>
+
+<div>
+<%# comment -%>
+</div>
 ```
 
 ##### HTML
 
 ```html
-<p></p>
+<div>
+
+</div>
+
+<div>
+</div>
 ```
 
 ### `<%`: Scriptlets
@@ -236,7 +247,7 @@ The use of scriptlets might cause some useless whitespace, as illustrated by
 the example below. You can trim it by
 
 1. using the `-%>` ending tag, and
-2. always starting the tag in the beginning of a line.
+2. using the `<%_` starting tag or starting the tag in the beginning of a line.
 
 #### Example
 
@@ -294,54 +305,93 @@ It does *not* mean that we recommend mixing coding styles in your own project.
 </dl>
 ```
 
+### `<%_` "Whitespace Slurping" Scriptlet
+
+This tag is the same as a Scriptlet, except that it removes all whitespace before it.
+
+#### Example
+
+##### EJS
+
+```html
+<ul>
+  <% users.forEach(function(user, i, arr){ -%>
+    <li><%= user %></li>
+  <% }); -%>
+</ul>
+
+<ul>
+  <%_ users.forEach(function(user, i, arr){ -%>
+    <li><%= user %></li>
+  <%_ }); -%>
+</ul>
+```
+
+##### HTML
+
+```html
+<ul>
+      <li>Anne</li>
+      <li>Bob</li>
+  </ul>
+
+<ul>
+    <li>Anne</li>
+    <li>Bob</li>
+</ul>
+```
+
 Ending tags
 -----------
 
-There are two flavors of ending tags: the regular one and the
-whitespace-trimming one.
+There are three flavors of ending tags: the regular one, the
+newline-trimming one, and the whitespace-slurping one.
 
 ### `%>`: Regular ending tag
 
 As used in all of the examples above, `%>` is the standard tag used to end an
 EJS expression.
 
-### `-%>`: Whitespace-trimming ending tag
+### `-%>`: Newline-trimming ending tag
 
-`-%>` trims all extra whitespace a scriptlet or a comment might cause. It does
+`-%>` trims all extra newlines a scriptlet or a comment might cause. It does
 not have any effect on output tags.
 
 #### Example
 
-This is the exact example from `<%` starting tag above, but with `%>`
-substituted by `-%>`.
-
 ##### EJS
 
-```js
+```html
 Beginning of template
 <%  'this is a statement'
  + ' that is long'
  + ' and long'
  + ' and long' %>
-This is indented so some spaces will still be left:
-  <% 'statement' -%>
-See?
-This is the proper way:
-<%   'statement' -%>
+End of template
+---
+Beginning of template
+<%  'this is a statement'
+ + ' that is long'
+ + ' and long'
+ + ' and long' -%>
 End of template
 ```
 
 ##### Output
 
-```
+```html
 Beginning of template
 
-This is indented so some spaces will still be left:
-  See?
-This is the proper way:
+End of template
+---
+Beginning of template
 End of template
 ```
 
+### `_%>`: Whitespace-slurping ending tag
+
+`_%>` removes all whitespace after it.
+
 Literal tag
 -----------