Document js and css filters handling of CDATA

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 3.2.0 (Unreleased)
 
+* The :javascript and :css filters no longer add CDATA tags when the format is
+  html4 or html5. This can be overridden by setting the `cdata` option to
+  `true`. CDATA tags are always added when the format is xhtml.
+
 * HTML2Haml has been extracted to a separate gem, creatively named "html2haml".
 
 * Haml's internals have been refactored to move the parser, compiler and options

REFERENCE.md

@@ -1092,8 +1092,9 @@ Tilt.
 
 {#css-filter}
 ### `:css`
-Surrounds the filtered text with `<style>` and CDATA tags. Useful for including
-inline CSS.
+Surrounds the filtered text with `<style>` and (optionally) CDATA tags. Useful
+for including inline CSS. Use the {Haml::Options#cdata `:cdata` option} to
+control when CDATA tags are added.
 
 {#erb-filter}
 ### `:erb`
@@ -1109,8 +1110,9 @@ before placing it in the document.
 
 {#javascript-filter}
 ### `:javascript`
-Surrounds the filtered text with `<script>` and CDATA tags.
-Useful for including inline Javascript.
+Surrounds the filtered text with `<script>` and (optionally) CDATA tags.
+Useful for including inline Javascript. Use the {Haml::Options#cdata `:cdata`
+option} to control when CDATA tags are added.
 
 {#less-filter}
 ### `:less`

lib/haml/options.rb

@@ -148,7 +148,11 @@ module Haml
     # Defaults to `true` in Rails production  mode, and `false` everywhere else.
     attr_accessor :ugly
 
-    # Whether to include CDATA sections around javascript blocks.
+    # Whether to include CDATA sections around javascript and css blocks when
+    # using the `:javascript` or `:css` filters.
+    #
+    # This option also affects the `:sass`, `:scss`, `:less` and `:coffeescript`
+    # filters.
     #
     # Defaults to `false` for html, `true` for xhtml. Cannot be changed when using
     # xhtml.