Extended docs for shortcode handling and doctypes (fixes #1700)

docs/en/topics/data-types.md

@@ -13,12 +13,12 @@ sentence in a longer piece of text.
 *  `[api:Date]`: A date field
 *  `[api:Decimal]`: A decimal number.
 *  `[api:Enum]`: An enumeration of a set of strings
-*  `[api:HTMLText]`: A variable-length string of up to 2 megabytes, designed to store HTML
+*  `[api:HTMLText]`: A variable-length string of up to 2MB, designed to store HTML
 *  `[api:HTMLVarchar]`: A variable-length string of up to 255 characters, designed to store HTML
 *  `[api:Int]`: An integer field.
 *  `[api:Percentage]`: A decimal number between 0 and 1 that represents a percentage.
 *  `[api:SS_Datetime]`: A date / time field
-*  `[api:Text]`: A variable-length string of up to 2 megabytes, designed to store raw text
+*  `[api:Text]`: A variable-length string of up to 2MB, designed to store raw text
 *  `[api:Time]`: A time field
 *  `[api:Varchar]`: A variable-length string of up to 255 characters, designed to store raw text
 
@@ -83,12 +83,15 @@ Example: Flagging an object of type `MyObject` (see above) if it's date is in th
 
 ## Casting HTML Text
 
-The database field types `[api:HTMLVarchar]` and `[api:Varchar]` are exactly the same in the database.  However, the 
+The database field types `[api:HTMLVarchar]`/`[api:HTMLText]` and `[api:Varchar]`/`[api:Text]` 
-templating engine knows to escape the `[api:Varchar]` field and not the `[api:HTMLVarchar]` field.  So, it's important you
+are exactly the same in the database.  However, the  templating engine knows to escape 
-use the right field if you don't want to be putting $FieldType.XML everywhere.
+fields without the `HTML` prefix automatically in templates,
+to prevent them from rendering HTML interpreted by browsers.
+This escaping prevents attacks like CSRF or XSS (see "[security](/topics/security)"),
+which is important if these fields store user-provided data.
 
-If you're going to put HTML content into the field, please use the field type with the HTML prefix.  Otherwise, you're
+You can disable this auto-escaping by using the `$MyField.RAW` escaping hints,
-going to risk double-escaping your data, forgetting to escape your data, and generally creating a confusing situation.
+or explicitly request escaping of HTML content via `$MyHtmlField.XML`.
 
 ## Related
 

docs/en/topics/rich-text-editing.md

@@ -5,7 +5,9 @@
 Editing and formatting content is the bread and butter of every content management system,
 which is why SilverStripe has a tight integration with our preferred editor library, [TinyMCE](http://tinymce.com).
 On top of the base functionality, we use our own insertion dialogs to ensure
-you can effectively select and upload files.
+you can effectively select and upload files. In addition to the markup managed by TinyMCE,
+we use [shortcodes](/reference/shortcodes) to store information about inserted
+images or media elements.
 
 ## Usage
 
@@ -153,6 +155,11 @@ files into the managed HTML content. It can be used both for referencing
 files on the webserver filesystem (through the `[api:File]` and `[api:Image]` APIs),
 as well as hotlinking files from the web. 
 
+We use [shortcodes](/reference/shortcodes) to store information about inserted images or media elements.
+The `[api:ShortcodeParser]` API post-processes the HTML content on rendering,
+and replaces the shortcodes accordingly. It also takes care of care of placing the
+shortcode replacements relative to its surrounding markup (e.g. left/right alignment).
+
 ## oEmbed: Embedding media through external services
 
 The ["oEmbed" standard](http://www.oembed.com/) is implemented by many media services
@@ -168,6 +175,27 @@ a cache, append `?flush=1` to a URL.
 
 To disable oEmbed usage, set the `Oembed.enabled` configuration property to "false".
 
+### Doctypes
+
+Since TinyMCE generates markup, it needs to know which doctype your documents
+will be rendered in. You can set this through the [element_format](http://www.tinymce.com/wiki.php/Configuration:element_format) configuration variable. It defaults to the stricter 'xhtml'
+setting, for example rendering self closing tags like `<br/>` instead of `<br>`.
+In case you want to adhere to HTML4 instead, use the following configuration:
+
+	:::php
+	HtmlEditorConfig::get('cms')->setOption('element_format', 'html');
+
+By default, TinyMCE and SilverStripe will generate valid HTML5 markup,
+but it will strip out HTML5 tags like `<article>` or `<figure>`.
+If you plan to use those, add them to the [valid_elements](http://www.tinymce.com/wiki.php/Configuration:valid_elements)
+configuration setting.
+
+Also, the `[api:SS_HTMLValue]` API underpinning the HTML processing parses the markup
+into a temporary object tree which can be traversed and modified before saving.
+The built-in parser only supports HTML4 and XHTML syntax. In order to successfully
+process HTML5 tags, please use the
+['silverstripe/html5' module](https://github.com/silverstripe/silverstripe-html5).
+
 ## Recipes
 
 ### Customizing the "Insert" panels