From bcd6047ce053e164764a6fc55f84645ba7c46253 Mon Sep 17 00:00:00 2001
From: adon <adon@yahoo-inc.com>
Date: Mon, 31 Aug 2015 00:50:36 +0800
Subject: [PATCH] updated README on tag balancing

---
 README.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/README.md b/README.md
index 2cefb57..12d4158 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,36 @@ var input = '...';
 var result = purifier.purify(input);
 ```
 
+## Advanced Usage
+
+The following outlines the configuration that is secure by default. You should perform due dilligence to confirm your use cases are safe before disabling or altering the configurations.
+
+```js
+// The default configuration
+new Purifier({
+	whitelistTags: ['a', '...'],
+	whitelistAttributes: ['href', '...'],
+	enableCanonicalization: true,
+	tagBalance: {
+		enabled: true,
+		stackSize: 100
+	}
+});
+```
+
+<!--
+#### whitelistTags
+
+#### whitelistAttributes
+
+#### enableCanonicalization
+-->
+
+#### tagBalance
+The untrusted data must be self-contained. Therefore, it cannot close any tags prior to its inclusion, nor leave any of its own tags unclosed. An efficient and simple tag balancing algorithm is applied by default to enforce this goal only, and may not produce perfectly balanced output. You may implement another tag balancing algorithm before invoking purify. But the default one should still be enabled, unless you're sure the self-contained requirement is met.
+
+The ``stackSize`` (default: 100) is a limit imposed on the maximum number of unclosed tags (or the max levels of nested tags). When an untrusted data attempts to open tags that are so nested and has exceeded the allowed limit, the algorithm will terminate and cease processing any data further but simply close all of those tags.
+
 ## Development
 
 ### How to build