Add advanced usage and TOC (#172)

* Add advanced usage and TOC

* Pngcrush

* Update haiku

Author: ascandella

Diff for: .gitignore

@@ -1,3 +1,4 @@
 work/
 target/
 .idea
+.DS_Store

Diff for: docs/advanced.md

@@ -0,0 +1,63 @@
+Advanced Usage
+==============
+
+In addition to Unit and Coverage results, this plugin supports two additional features
+you may want to take use of. Both options take a maximum number of bytes to copy, since the plugin
+is executed on the Jenkins master and syncing multiple megabytes of data can cause
+performance problems.
+
+Custom Comments
+---------------
+
+If you'd like to post additional text back to Phabricator, you can add text to the `.phabricator-comment` file
+(you can change the name of the file in your job configuration page):
+
+![Comment Configuration](/docs/custom-comment.png)
+
+Any text present in this file will be echoed verbatim to the comment that Jenkins posts back to
+Phabricator. If you'd like to preserve formatting, check the "Preserve Formatting" block and the
+plugin will surround the comment in triple-backticks (```)
+
+Custom Lint
+-----------
+
+If you'd like to send Lint Violations as well, you can echo Harbormaster-compatible JSON
+(where each line is a valid JSON dictionary) into the `.phabricator-lint` file.
+
+Although each **line** must be valid JSON, note that the file as a whole is **not valid JSON**
+(e.g. if you call `JSON.parse('.phabricator-lint')`) it will fail. This is a design decision to
+make it easy for build scripts to `tee` (echo line-by-line) violations without having to
+produce well-formed JSON, which requires knowing upfront how many violations are present.
+
+![Lint Configuration](/docs/custom-lint.png)
+
+If a job was configured to run the following shell script:
+
+```bash
+mkdir example
+echo "Once upon a time\nThere was a Jenkins plugin" > example/path
+# NOTE: tee -a to support appending multiple lints
+echo '{"name": "Comment Name", "code": "Haiku", "severity": "error", "path": "example/path", "line": 2, "char": 0, "description": "Line is not a Haiku" }' | tee -a .phabricator-lint
+```
+
+You would see the following in your differential at the top:
+
+![Inline Diff Lint](/docs/example-path-haiku.png)
+
+And the following in the code view:
+
+![Inline Diff Lint](/docs/inline-haiku.png)
+
+See [Harbormaster Lint](https://secure.phabricator.com/conduit/method/harbormaster.sendmessage/)
+API for details on the supported JSON keys. `line`, `char`, and `description` are all optional.
+The rest are required.
+
+The severity parameter recognizes these severity levels:
+
+| Key      | Name     |
+|----------|----------|
+| advice   | Advice   |
+| autofix  | Auto-Fix |
+| warning  | Warning  |
+| error    | Error    |
+| disabled | Disabled |

Diff for: docs/configure-job-parameters.png

@@ -7,6 +7,20 @@ if Harbormaster is not enabled).
 [Phabricator]: http://phabricator.org/
 [Jenkins]: https://jenkins-ci.org/
 
+Table of Contents
+=================
+* [Configuration](#configuration)
+  * [Phabricator Configuration](#phabricator-configuration)
+  * [Jenkins Setup](#jenkins-setup)
+* [Usage](#usage)
+  * [Jenkins Job](#jenkins-job)
+  * [Harbormaster](#harbormaster)
+  * [Herald](#herald)
+* [Advanced Usage](docs/advanced.md)
+* [Test Your Configuration](#test-your-configuration)
+* [Development](#development)
+* [Testing](#testing)
+
 Configuration
 =============
 
@@ -56,7 +70,7 @@ Jenkins Job
   1. Navigate to the **Post-build Actions** section.
   2. Click the **Add post-build action** button and select **Post to Phabricator**.
   3. Make sure the **Comment on Success** and **Comment with console link on Failure** checkboxes are selected.
-  4. Optionally: 
+  4. Optionally:
     1. If you have [Uberalls](https://github.com/uber/uberalls) enabled, enter a path to scan for Cobertura reports.
     2. If you want to post additional text to Phabricator other than "Pass" and "Fail", select the **Add Custom Comment** checkbox. Then create a `.phabricator-comment` file and enter the text you want Jenkins to add to the build status comment in Phabricator.
 ![Add post-build action](/docs/configure-job-post-build.png)
@@ -75,9 +89,9 @@ With Phabricator, Jenkins, and your Jenkins jobs configured it's time to configu
 7. Use this template URI to fill in the URI field for the build plan: `https://ci.example.com/buildByToken/buildWithParameters?job=test-example&DIFF_ID=${buildable.diff}&PHID=${target.phid}`
 
 	Be sure to replace `https://ci.example.com` with the URI of your Jenkins instance and `test-example` with the name of your Jenkins job.
-	
+
 	If your Jenkins instance is exposed to the internet, make sure to install the [Build Token Root Plugin][] and fill in the `token` parameter.
-	
+
 [Build Token Root Plugin]: https://wiki.jenkins-ci.org/display/JENKINS/Build+Token+Root+Plugin
 
 8. Click the **When Complete** dropdown menu and select **Wait For Message**.
@@ -110,6 +124,12 @@ commenting on your diff:
 
 ![Example](/docs/uberalls-integration.png)
 
+Advanced Usage
+--------------
+
+Now that you have build status and optionally coverage data set up, check out some
+[advanced features](docs/advanced.md).
+
 Development
 -----------