Adds table comparison of vendor and files

help/examples.md

@@ -203,7 +203,9 @@ of file paths would you put inside `vendor` but not inside `files`?
 
 A path inside the `files` property such as `scripts/main.js` will be transformed
 to `assets/scripts/main.js` if your manifest's `paths.source` is `assets/` and
-the dependency's `external` property is not set to `true`.
+the dependency's `external` property is not set to `true`. The `vendor` property
+paths are relative to your project root. If you are using gulp, this is
+typically where your gulpfile.js is located.
 
 It follows that you would want to put all your first-party project scripts
 inside the `files` property. Feel free to run your linters, styleguide checkers,
@@ -213,6 +215,45 @@ The `vendor` property is for third-party code you have no control over. You
 should not run project-specific linters, styleguide checkers, beautifiers, etc.
 on these files.
 
+
+#### Example
+
+This assumes your `path.source` is `assets/` and the dependency's `external`
+property is not explicitly set to `true`. Assume a project structure such as:
+
+<pre><code>
+.
+├── gulpfile.js
+├── assets/
+│   └── scripts/
+│       └── main.js
+└── vendor/
+    └── foundry/
+        └── flexslider.min.js
+</code></pre>
+
+<table class="table">
+  <thead>
+    <tr>
+      <th>Property</th>
+      <th>Path Before</th>
+      <th>Path After</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>files</code></td>
+      <td><code>scripts/main.js</code></td>
+      <td><code>assets/scripts/main.js</code></td>
+    </tr>
+    <tr>
+      <td><code>vendor</code></td>
+      <td><code>vendor/foundry/flexslider.min.js</code></td>
+      <td><code>vendor/foundry/flexslider.min.js</code></td>
+    </tr>
+  </tbody>
+</table>
+
 [gulp]: http://gulpjs.com/
 [dependency]: spec.md#serialization-dependency
 [paths]: spec.md#serialization-paths

help/spec.md

@@ -228,7 +228,12 @@ A more extensive `manifest.json` follows.
     <tr>
       <td>external</td>
       <td>boolean</td>
-      <td>Describes whether or not the source (`path.source`) directory will be prepended to each glob in the "files" property. A Dependency MAY have an "external" property.</td>
+      <td>
+        Describes whether or not the source (`path.source`) directory will be
+        prepended to each glob in the "files" property. A Dependency MAY have an
+        "external" property. The external property should be considered `false`
+        by default.
+      </td>
     </tr>
   </tbody>
 </table>