[Sass] Update docs about defining custom functions.

doc-src/FAQ.md

@@ -154,8 +154,17 @@ but it's not a great idea to put much logic in there anyway
 due to how browsers handle them.
 
 If you really need some sort of dynamic CSS,
-the best thing to do is put only the snippet you need to dynamically set
-in the `head` of your HTML document.
+you can define your own {Sass::Script::Functions Sass functions} using Ruby
+that can access the database or other configuration.
+*Be aware when doing this that Sass files are by default only compiled once
+and then served statically.*
+
+If you really, really need to compile Sass on each request,
+first make sure you have adequate caching set up.
+Then you can use {Sass::Engine} to render the code,
+using the {file:SASS_REFERENCE.md#custom-option `:custom` option}
+to pass in data that {Sass::Script::Functions::EvaluationContext#options can be accessed}
+from your Sass functions.
 
 ## You still haven't answered my question!
 

doc-src/SASS_REFERENCE.md

@@ -203,6 +203,10 @@ Available options are:
   as a comment. Useful for debugging especially when using imports
   and mixins.
 
+{#custom-option} `:custom`
+: An option that's available for individual applications to set
+  to make data available to {Sass::Script::Functions custom Sass functions}.
+
 ## CSS Rules
 
 Rules in flat CSS have two elements:

lib/sass/script/functions.rb

@@ -54,11 +54,16 @@ module Sass::Script
   #
   # Second, making Ruby functions accessible from Sass introduces the temptation
   # to do things like database access within stylesheets.
-  # This temptation must be resisted.
-  # Keep in mind that Sass stylesheets are only compiled once
-  # at a somewhat indeterminate time
-  # and then left as static CSS files.
-  # Any dynamic CSS should be left in `<style>` tags in the HTML.
+  # This is generally a bad idea;
+  # since Sass files are by default only compiled once,
+  # dynamic code is not a great fit.
+  #
+  # If you really, really need to compile Sass on each request,
+  # first make sure you have adequate caching set up.
+  # Then you can use {Sass::Engine} to render the code,
+  # using the {file:SASS_REFERENCE.md#custom-option `options` parameter}
+  # to pass in data that {EvaluationContext#options can be accessed}
+  # from your Sass functions.
   #
   # Within one of the functions in this module,
   # methods of {EvaluationContext} can be used.