More on docs

[kgcab]

I wrote up some docs for doT. Do these look largely correct?

-------

doT is a JavaScript package that supports runtime expansion of string templates.
It was inspired by templating functions from jQote2.js (a jQuery plugin) 
by aefxx (http://aefxx.com/jquery-plugins/jqote2/)
and underscore.js (http://documentcloud.github.com/underscore/).

You can find doT at https://github.com/olado/doT
It was created and is maintained by Laura Doktorova.
It is licensed under the MIT license.

The doT package:
     doT.template(template, templateSettings, defininitions) - Function
        template = string (or stringifiable object) representing the template to be compiled.
        templateSettings = associative array that defines various compiler settings (see Template Settings)
        definitions = associative array accessed using the 'def' directive in templates
                    these are intended to support interpolation at template compile time
                    (note: examples imply this contains functions such as loadFile by default. It does not.
                     That example assumes the function loadFile is available in the current JavaScript context.)

         Compiles the given template and returns a function that can be used to expand that template on demand.
         The resulting function takes one argument, whose name may be changed using Template Settings:
             it = an associative array of values that may be referenced during expansion of the template
          
      doT.templateSettings - associative array
          evaluate = regular expression used to locate and replace runtime evaluations in the template string
          interpolate = regular expression used to locate and replace runtime interpolations in the template string
          encode = regular expression used to locate and replace runtime interpolations which will be HTML encoded 
                  prior to insertion in the template string
          use = regular expression used to locate and replace compile time interpolation in the template string
          define = regular expression used to locate and replace compile time variable definitions in the template string
          varname = the name of the single argument to the function produced by doT.template
                  this is the associative array referenced by runtime interpolation and evaluation
          strip = Boolean that controls whether or not end of line characters, CDATA tags, and comments 
                  will be removed from compiled templates
                  defaults to true
          append = Boolean that controls how interpolations are written in the compiled template.
                  The compiled template is just a JS function that binds a string to 'out'.
                  If true then interpolations are written as "+(\<interpolation\>)+", resulting in one long string concatenation.
                  if false then interpolations are written as ";out+=(\<interpolation\>);out+=", resulting in a series of 
                          separate concatenations.
                  In some browsers, options one will be faster while option two will be faster in others. The choice is left to the user.
                  Note: I believe the second case will break if two interpolations are placed with no characters between them. Check.
                  defaults to true

Some definitions:
     template - a string containing directives that fetch values from the JavaScript environment in order to construct a new string
                  this can be used to dynamically construct portions of your web page using values fetched, for example, using AJAX calls to a service.
     interpolate - to add text to either the template itself at compiletime or to the expanded string at runtime
     evaluate - to execute a bit of JavaScript and use the value returned
     expansion - the process of taking each of the directives in a template and performing the task it specifies
                  the results are inserted into the result string in place of the directive
                  because the results are often larger than the directives themselves, we think of this as expanding the template 
                          into the result
     HTML encode - sometimes strings contain letters (characters) that have special meanings in HTML
                  HTML encoding such a string marks those letters such that a browsers will just display the letters and not treat 
                          them as directions

doT directives:
     compiletime definition = evaluate code at compile time and store in the 'definitions' associative array
                 Note that the 'definitions' are only available at compiletime (via the 'def' variable in JavaScript)
                      so these values will be consumed by 'use' directives, presumably
                 default syntax has several options:
                            "{{##<definition>:<value>}}"
                            "{{##def.<definition>=<value>}}"

                 if the 'definitions' argument passed to doT.template does not contain an entry that matches <definition>
                      if our assignment character is ':' we set definitions[<definition>] to the string <value>
                      if our assignment character is '=' we evaluate <value> in the current JavaScript context and set 
                              definitions[<definition>] to that value
                 The 'definition' directive is removed from the template and no new text is inserted in its place. 
                 The 'definitions' associative array is exposed as 'def' in the current JavaScript environment for 'use' directives.
                 Authors may rely on 'definition' and 'use' directives being evaluated in the order they occur in the template.
                 
                 Note:
                 The examples supplied actually cannot all be parsed by default (they lack the assignment character and value).

      compiletime use = interpolate at compiletime, with recursive expansion of 'definition' and 'use' directives.
                  default syntax:
                          "{{#<code>}}"
                  Evaluates <code> in the current JavaScript context.
                       if <code> is not undefined, recursively expand 'definition' and 'use' directives that might be found in that string.
                       call toString() on other types of objects returned before performing this expansion.
                  The resulting string is inserted into the compiled template in place of the 'use' directive. 
                  Authors may rely on 'definition' and 'use' directives being evaluated in the order they occur in the template.
                  The 'definitions' associative array is exposed as 'def' in the current JavaScript environment.
                  Note: there is no attempt to prevent infinite recursion. A recursion counter would be a VERY VERY good idea.
                  
      runtime interpolate = evaluate code in the current JavaScript context and insert the value returned into the resulting string 
                  default syntax:
                          "{{=<code>}}"
                  Evaluates <code> in the current JavaScript context. 
                  The result is inserted into the result string in place of the 'interpolate' directive.
                  Note: the code is evaluated after all other runtime directives have been expanded into code.
                  All runtime code is then evaluated en masse. One should not count on these being evaluated in order
                         as that assumption is subject to the whim of the JavaScript interpreter. 

      runtime encode = evaluate code in the current JavaScript context and insert the value returned into the resulting string 
                  default syntax:
                          "{{!<code>}}"
                  Evaluates <code> in the current JavaScript context. 
                  The result is first HTM encoded (lightly) then  inserted into the result string in place of the 'encode' directive.
                  Note: the code is evaluated after all other runtime directives have been expanded into code.
                  All runtime code is then evaluated en masse. One should not count on these being evaluated in order
                         as that assumption is subject to the whim of the JavaScript interpreter.

      runtime evaluate = evaluate code in the current JavaScript context but DO NOT insert the value into the result string 
                  default syntax:
                          "{{<code>}}"
                  Evaluates <code> in the current JavaScript context. 
                  The result is NOT inserted into the result string. 
                  The strings resulting from 'print' calls in <code> WILL be inserted into the result string in the order they occur.
                  The 'evaluate' directive is removed from the result string.
                  Note: the code is evaluated after all other runtime directives have been expanded into code.
                  All runtime code is then evaluated en masse. One should not count on these being evaluated in order
                         as that assumption is subject to the whim of the JavaScript interpreter.

[epoberezkin]

@kgcab is it still relevant or mainly included in docs already? I will review anyway