Security - Improve "HTML output" content

docs/security/index.md

@@ -97,7 +97,7 @@ Now that we understand the difference between inputs and outputs, as well as the
 
 ### In an ideal world {:#ideal}
 
-Ideally developers should do the following.
+Within the larger community of developers (outside of CiviCRM), the current [best-practices say](https://security.stackexchange.com/a/95330/32455) that developer should do the following
 
 * For inputs:
     * **Validate data inputs** as strictly as possible.

docs/security/inputs.md

@@ -31,11 +31,13 @@ if (!preg_match(':^[a-zA-Z0-9\-_/]+$:', $angPage)) {
 
 ## `POST` parameters
 
-TODO
+When accepting `POST` parameters through forms, it's important to validate the data as 
 
 
 ## When saving to the database
 
+Despite the [current recommended best-practices](/security/index.md#input-vs-output), CiviCRM *does* sanitize some of its *inputs*. This section describes how.
+
 ### Input encoding {:#input-encoding}
 
 For almost all inputs which are saved to the database, CiviCRM automatically uses `CRM_Utils_API_HTMLInputCoder::encodeInput()` to apply a *partial* encoding for HTML output. This encoding step happens at a low level for inputs passed through the API or the BAO (except for fields noted in `CRM_Utils_API_HTMLInputCoder::getSkipFields()`). So if you're using the API or the BAO to process your input you don't need to do anything special.

docs/security/outputs.md

@@ -2,24 +2,51 @@
 
 ## HTML/Smarty {:#html}
 
-### Between tags {:#between-tags}
+Untrusted data placed in HTML must be [encoded](/security/index.md#encoding) for HTML output at some point. The PHP function [htmlentities()](http://php.net/manual/en/function.htmlentities.php) does this, and the Smarty variable modifier [escape](https://www.smarty.net/docsv2/en/language.modifier.escape) behaves similarly.
 
-When placing data between tags, no output encoding is necessary. For example:
+### Between tags {:#db-between-tags}
+
+#### Database data between tags {:#db-between-tags}
+
+Data which comes out of MySQL has already been [partially encoded for HTML output](/security/inputs.md#input-encoding). This means that when you place this data between HTML tags, you don't need to perform any output encoding. For example:
 
 ```html
 <div>{$displayName}</div>
+```
+
+#### Direct user input between tags {:#inputs-between-tags}
+
+Here we have a bit of a grey area where CiviCRM does not have a consistent approach. If untrusted inputs are placed into HTML before being saved to the database, you need to ensure to perform HTML output encoding *at some point*.
+
+You can perform the output encoding in PHP as follows:
+
+```php
+$userInput = htmlentities($userInput);
+```
+
+Or you can perform the output encoding in Smarty as follows:
+
+```html
+<div>{$userInput|escape}</div>
 ``` 
 
-### In attributes {:#in-attributes}
+!!! tip
+    Be wary of using user input in *error messages*. This is a common scenario wherein untrusted user input can end up in HTML with no HTML output encoding.
 
-When placing data within attributes, use Smarty's [escape](https://www.smarty.net/docsv2/en/language.modifier.escape) variable modifier to encode HTML entities.
+### HTML attributes {:#in-attributes}
+
+When placing data within attributes, always use Smarty's [escape](https://www.smarty.net/docsv2/en/language.modifier.escape) variable modifier to encode HTML entities.
 
 ```html
 <a href="#" title="{$displayName|escape}">Foo</a>
 ```
 
 !!! note
-    HTML output encoding *is* necessary for attribute data (but *not* necessary for data between tags) because of the intentionally incomplete [input encoding](/security/inputs.md#input-encoding) that CiviCRM performs. 
+    HTML output encoding *is always* necessary for attribute data (but *not* always necessary for data between tags) because of the intentionally incomplete [input encoding](/security/inputs.md#input-encoding) that CiviCRM performs. 
+    
+## Javascript {:#in-javascript}
+
+TODO
 
 ## AngularJS templates {:#angularjs}