Feature/add docs (#689)

* Add converted docs repo

* Set theme jekyll-theme-minimal

* Removed BC docs, added TOC

* Added TOCs, rewrote most important links in documentation. Linked README to new Github Pages site

* some link fixes

docs/programmers/api-variables/variable-allow-php-templates.md

@@ -0,0 +1,18 @@
+\$allow\_php\_templates {#variable.allow.php.templates}
+=======================
+
+By default the PHP template file resource is disabled. Setting
+`$allow_php_templates` to TRUE will enable PHP template files.
+
+::: {.informalexample}
+
+    <?php
+    $smarty->allow_php_templates = true;
+    ?>
+
+            
+:::
+
+> **Note**
+>
+> The PHP template file resource is an undocumented deprecated feature.

docs/programmers/api-variables/variable-auto-literal.md

@@ -0,0 +1,17 @@
+\$auto\_literal {#variable.auto.literal}
+===============
+
+The Smarty delimiter tags { and } will be ignored so long as they are
+surrounded by white space. This behavior can be disabled by setting
+auto\_literal to false.
+
+::: {.informalexample}
+
+    <?php
+    $smarty->auto_literal = false;
+    ?>
+
+            
+:::
+
+See also [Escaping Smarty Parsing](#language.escaping),

docs/programmers/api-variables/variable-autoload-filters.md

@@ -0,0 +1,21 @@
+\$autoload\_filters {#variable.autoload.filters}
+===================
+
+If there are some filters that you wish to load on every template
+invocation, you can specify them using this variable and Smarty will
+automatically load them for you. The variable is an associative array
+where keys are filter types and values are arrays of the filter names.
+For example:
+
+::: {.informalexample}
+
+    <?php
+    $smarty->autoload_filters = array('pre' => array('trim', 'stamp'),
+                                      'output' => array('convert'));
+    ?>
+
+            
+:::
+
+See also [`registerFilter()`](#api.register.filter) and
+[`loadFilter()`](#api.load.filter)

docs/programmers/api-variables/variable-cache-dir.md

@@ -0,0 +1,35 @@
+\$cache\_dir {#variable.cache.dir}
+============
+
+This is the name of the directory where template caches are stored. By
+default this is `./cache`, meaning that Smarty will look for the
+`cache/` directory in the same directory as the executing php script.
+**This directory must be writeable by the web server**, [see
+install](#installing.smarty.basic) for more info.
+
+You can also use your own [custom cache implementation](#caching.custom)
+to control cache files, which will ignore this setting. See also
+[`$use_sub_dirs`](#variable.use.sub.dirs).
+
+> **Note**
+>
+> This setting must be either a relative or absolute path. include\_path
+> is not used for writing files.
+
+> **Note**
+>
+> It is not recommended to put this directory under the web server
+> document root.
+
+> **Note**
+>
+> As of Smarty 3.1 the attribute \$cache\_dir is no longer accessible
+> directly. Use [`getCacheDir()`](#api.get.cache.dir) and
+> [`setCacheDir()`](#api.set.cache.dir) instead.
+
+See also [`getCacheDir()`](#api.get.cache.dir),
+[`setCacheDir()`](#api.set.cache.dir), [`$caching`](#variable.caching),
+[`$use_sub_dirs`](#variable.use.sub.dirs),
+[`$cache_lifetime`](#variable.cache.lifetime),
+[`$cache_modified_check`](#variable.cache.modified.check) and the
+[caching section](#caching).

docs/programmers/api-variables/variable-cache-id.md

@@ -0,0 +1,11 @@
+\$cache\_id {#variable.cache.id}
+===========
+
+Persistent cache\_id identifier. As an alternative to passing the same
+`$cache_id` to each and every function call, you can set this
+`$cache_id` and it will be used implicitly thereafter.
+
+With a `$cache_id` you can have multiple cache files for a single call
+to [`display()`](#api.display) or [`fetch()`](#api.fetch) depending for
+example from different content of the same template. See the [caching
+section](#caching) for more information.

docs/programmers/api-variables/variable-cache-lifetime.md

@@ -0,0 +1,30 @@
+\$cache\_lifetime {#variable.cache.lifetime}
+=================
+
+This is the length of time in seconds that a template cache is valid.
+Once this time has expired, the cache will be regenerated.
+
+-   `$caching` must be turned on (either
+    Smarty::CACHING\_LIFETIME\_CURRENT or
+    Smarty::CACHING\_LIFETIME\_SAVED) for `$cache_lifetime` to have any
+    purpose.
+
+-   A `$cache_lifetime` value of -1 will force the cache to never
+    expire.
+
+-   A value of 0 will cause the cache to always regenerate (good for
+    testing only, to disable caching a more efficient method is to set
+    [`$caching`](#variable.caching) = Smarty::CACHING\_OFF).
+
+-   If you want to give certain templates their own cache lifetime, you
+    could do this by setting [`$caching`](#variable.caching) =
+    Smarty::CACHING\_LIFETIME\_SAVED, then set `$cache_lifetime` to a
+    unique value just before calling [`display()`](#api.display) or
+    [`fetch()`](#api.fetch).
+
+If [`$force_compile`](#variable.force.compile) is enabled, the cache
+files will be regenerated every time, effectively disabling caching. You
+can clear all the cache files with the
+[`clear_all_cache()`](#api.clear.all.cache) function, or individual
+cache files (or groups) with the [`clear_cache()`](#api.clear.cache)
+function.

docs/programmers/api-variables/variable-cache-locking.md

@@ -0,0 +1,11 @@
+\$cache\_locking {#variable.cache.locking}
+================
+
+Cache locking avoids concurrent cache generation. This means resource
+intensive pages can be generated only once, even if they\'ve been
+requested multiple times in the same moment.
+
+Cache locking is disabled by default. To enable it set `$cache_locking`
+to TRUE.
+
+See also [`$locking_timeout`](#variable.locking.timeout)

docs/programmers/api-variables/variable-cache-modified-check.md

@@ -0,0 +1,12 @@
+\$cache\_modified\_check {#variable.cache.modified.check}
+========================
+
+If set to TRUE, Smarty will respect the If-Modified-Since header sent
+from the client. If the cached file timestamp has not changed since the
+last visit, then a `'304: Not Modified'` header will be sent instead of
+the content. This works only on cached content without
+[`{insert}`](#language.function.insert) tags.
+
+See also [`$caching`](#variable.caching),
+[`$cache_lifetime`](#variable.cache.lifetime), and the [caching
+section](#caching).

docs/programmers/api-variables/variable-caching-type.md

@@ -0,0 +1,9 @@
+\$caching\_type {#variable.caching.type}
+===============
+
+This property specifies the name of the caching handler to use. It
+defaults to `file`, enabling the internal filesystem based cache
+handler.
+
+See [Custom Cache Implementation](#caching.custom) for pointers on
+setting up your own cache handler.

docs/programmers/api-variables/variable-caching.md

@@ -0,0 +1,38 @@
+\$caching {#variable.caching}
+=========
+
+This tells Smarty whether or not to cache the output of the templates to
+the [`$cache_dir`](#variable.cache.dir). By default this is set to the
+constant Smarty::CACHING\_OFF. If your templates consistently generate
+the same content, it is advisable to turn on `$caching`, as this may
+result in significant performance gains.
+
+You can also have [multiple](#caching.multiple.caches) caches for the
+same template.
+
+-   A constant value of Smarty::CACHING\_LIFETIME\_CURRENT or
+    Smarty::CACHING\_LIFETIME\_SAVED enables caching.
+
+-   A value of Smarty::CACHING\_LIFETIME\_CURRENT tells Smarty to use
+    the current [`$cache_lifetime`](#variable.cache.lifetime) variable
+    to determine if the cache has expired.
+
+-   A value of Smarty::CACHING\_LIFETIME\_SAVED tells Smarty to use the
+    [`$cache_lifetime`](#variable.cache.lifetime) value at the time the
+    cache was generated. This way you can set the
+    [`$cache_lifetime`](#variable.cache.lifetime) just before
+    [fetching](#api.fetch) the template to have granular control over
+    when that particular cache expires. See also
+    [`isCached()`](#api.is.cached).
+
+-   If [`$compile_check`](#variable.compile.check) is enabled, the
+    cached content will be regenerated if any of the templates or config
+    files that are part of this cache are changed.
+
+-   If [`$force_compile`](#variable.force.compile) is enabled, the
+    cached content will always be regenerated.
+
+See also [`$cache_dir`](#variable.cache.dir),
+[`$cache_lifetime`](#variable.cache.lifetime),
+[`$cache_modified_check`](#variable.cache.modified.check),
+[`is_cached()`](#api.is.cached) and the [caching section](#caching).

docs/programmers/api-variables/variable-compile-check.md

@@ -0,0 +1,27 @@
+\$compile\_check {#variable.compile.check}
+================
+
+Upon each invocation of the PHP application, Smarty tests to see if the
+current template has changed (different timestamp) since the last time
+it was compiled. If it has changed, it recompiles that template. If the
+template has yet not been compiled at all, it will compile regardless of
+this setting. By default this variable is set to TRUE.
+
+Once an application is put into production (ie the templates won\'t be
+changing), the compile check step is no longer needed. Be sure to set
+`$compile_check` to FALSE for maximum performance. Note that if you
+change this to FALSE and a template file is changed, you will \*not\*
+see the change since the template will not get recompiled.
+
+If [`$caching`](#variable.caching) is enabled and `$compile_check` is
+enabled, then the cache files will get regenerated if an involved
+template file or config file was updated.
+
+As of Smarty 3.1 `$compile_check` can be set to the value
+`Smarty::COMPILECHECK_CACHEMISS`. This enables Smarty to revalidate the
+compiled template, once a cache file is regenerated. So if there was a
+cached template, but it\'s expired, Smarty will run a single
+compile\_check before regenerating the cache.
+
+See [`$force_compile`](#variable.force.compile) and
+[`clearCompiledTemplate()`](#api.clear.compiled.tpl).

docs/programmers/api-variables/variable-compile-dir.md

@@ -0,0 +1,29 @@
+\$compile\_dir {#variable.compile.dir}
+==============
+
+This is the name of the directory where compiled templates are located.
+By default this is `./templates_c`, meaning that Smarty will look for
+the `templates_c/` directory in the same directory as the executing php
+script. **This directory must be writeable by the web server**, [see
+install](#installing.smarty.basic) for more info.
+
+> **Note**
+>
+> This setting must be either a relative or absolute path. include\_path
+> is not used for writing files.
+
+> **Note**
+>
+> It is not recommended to put this directory under the web server
+> document root.
+
+> **Note**
+>
+> As of Smarty 3.1 the attribute \$compile\_dir is no longer accessible
+> directly. Use [`getCompileDir()`](#api.get.compile.dir) and
+> [`setCompileDir()`](#api.set.compile.dir) instead.
+
+See also [`getCompileDir()`](#api.get.compile.dir),
+[`setCompileDir()`](#api.set.compile.dir),
+[`$compile_id`](#variable.compile.id) and
+[`$use_sub_dirs`](#variable.use.sub.dirs).

docs/programmers/api-variables/variable-compile-id.md

@@ -0,0 +1,44 @@
+\$compile\_id {#variable.compile.id}
+=============
+
+Persistant compile identifier. As an alternative to passing the same
+`$compile_id` to each and every function call, you can set this
+`$compile_id` and it will be used implicitly thereafter.
+
+If you use the same template with different [pre- and/or
+post-filters](#plugins.prefilters.postfilters) you must use a unique
+`$compile_id` to keep the compiled template files separated.
+
+For example a [prefilter](#plugins.prefilters.postfilters) that
+localizes your templates (that is: translates language dependend parts)
+at compile time, then you could use the current language as
+`$compile_id` and you will get a set of compiled templates for each
+language you use.
+
+
+    <?php
+    $smarty->compile_id = 'en';
+    ?>
+
+      
+
+Another application would be to use the same compile directory across
+multiple domains / multiple virtual hosts.
+
+
+    <?php
+
+    $smarty->compile_id = $_SERVER['SERVER_NAME'];
+    $smarty->compile_dir = '/path/to/shared_compile_dir';
+
+    ?>
+
+      
+
+> **Note**
+>
+> In Smarty 3 a `$compile_id` is no longer required to keep templates
+> with same name in different [`$template_dir`
+> folders](#variable.template.dir) separated. The [`$template_dir` file
+> path](#variable.template.dir) is encoded in the file name of compiled
+> and cached template files.

docs/programmers/api-variables/variable-compile-locking.md

@@ -0,0 +1,7 @@
+\$compile\_locking {#variable.compile.locking}
+==================
+
+Compile locking avoids concurrent compilation of the same template.
+
+Compile locking is enabled by default. To disable it set
+`$compile_locking` to FALSE.

docs/programmers/api-variables/variable-compiler-class.md

@@ -0,0 +1,6 @@
+\$compiler\_class {#variable.compiler.class}
+=================
+
+Specifies the name of the compiler class that Smarty will use to compile
+the templates. The default is \'Smarty\_Compiler\'. For advanced users
+only.

docs/programmers/api-variables/variable-config-booleanize.md

@@ -0,0 +1,8 @@
+\$config\_booleanize {#variable.config.booleanize}
+====================
+
+If set to TRUE, [config files](#config.files) values of `on/true/yes`
+and `off/false/no` get converted to boolean values automatically. This
+way you can use the values in the template like so:
+`{if #foobar#}...{/if}`. If foobar was `on`, `true` or `yes`, the `{if}`
+statement will execute. Defaults to TRUE.

docs/programmers/api-variables/variable-config-dir.md

@@ -0,0 +1,23 @@
+\$config\_dir {#variable.config.dir}
+=============
+
+This is the directory used to store [config files](#config.files) used
+in the templates. Default is `./configs`, meaning that Smarty will look
+for the `configs/` directory in the same directory as the executing php
+script.
+
+> **Note**
+>
+> It is not recommended to put this directory under the web server
+> document root.
+
+> **Note**
+>
+> As of Smarty 3.1 the attribute \$config\_dir is no longer accessible
+> directly. Use [`getConfigDir()`](#api.get.config.dir),
+> [`setConfigDir()`](#api.set.config.dir) and
+> [`addConfigDir()`](#api.add.config.dir) instead.
+
+See also [`getConfigDir()`](#api.get.config.dir),
+[`setConfigDir()`](#api.set.config.dir) and
+[`addConfigDir()`](#api.add.config.dir).

docs/programmers/api-variables/variable-config-overwrite.md

@@ -0,0 +1,40 @@
+\$config\_overwrite {#variable.config.overwrite}
+===================
+
+If set to TRUE, the default then variables read in from [config
+files](#config.files) will overwrite each other. Otherwise, the
+variables will be pushed onto an array. This is helpful if you want to
+store arrays of data in config files, just list each element multiple
+times.
+
+This examples uses [`{cycle}`](#language.function.cycle) to output a
+table with alternating red/green/blue row colors with
+`$config_overwrite` = FALSE.
+
+The config file.
+
+
+    # row colors
+    rowColors = #FF0000
+    rowColors = #00FF00
+    rowColors = #0000FF
+
+        
+
+The template with a [`{section}`](#language.function.section) loop.
+
+
+    <table>
+      {section name=r loop=$rows}
+      <tr bgcolor="{cycle values=#rowColors#}">
+        <td> ....etc.... </td>
+      </tr>
+      {/section}
+    </table>
+
+        
+
+See also [`{config_load}`](#language.function.config.load),
+[`getConfigVars()`](#api.get.config.vars),
+[`clearConfig()`](#api.clear.config), [`configLoad()`](#api.config.load)
+and the [config files section](#config.files).

docs/programmers/api-variables/variable-config-read-hidden.md

@@ -0,0 +1,8 @@
+\$config\_read\_hidden {#variable.config.read.hidden}
+======================
+
+If set to TRUE, hidden sections ie section names beginning with a
+period(.) in [config files](#config.files) can be read from templates.
+Typically you would leave this FALSE, that way you can store sensitive
+data in the config files such as database parameters and not worry about
+the template loading them. FALSE by default.

docs/programmers/api-variables/variable-debug-template.md

@@ -0,0 +1,9 @@
+\$debug\_tpl {#variable.debug_template}
+============
+
+This is the name of the template file used for the debugging console. By
+default, it is named `debug.tpl` and is located in the
+[`SMARTY_DIR`](#constant.smarty.dir).
+
+See also [`$debugging`](#variable.debugging) and the [debugging
+console](#chapter.debugging.console) section.

docs/programmers/api-variables/variable-debugging-ctrl.md

@@ -0,0 +1,20 @@
+\$debugging\_ctrl {#variable.debugging.ctrl}
+=================
+
+This allows alternate ways to enable debugging. `NONE` means no
+alternate methods are allowed. `URL` means when the keyword
+`SMARTY_DEBUG` is found in the `QUERY_STRING`, debugging is enabled for
+that invocation of the script. If [`$debugging`](#variable.debugging) is
+TRUE, this value is ignored.
+
+
+    <?php
+    // shows debug console only on localhost ie
+    // http://localhost/script.php?foo=bar&SMARTY_DEBUG
+    $smarty->debugging = false; // the default
+    $smarty->debugging_ctrl = ($_SERVER['SERVER_NAME'] == 'localhost') ? 'URL' : 'NONE';
+    ?>
+
+See also [debugging console](#chapter.debugging.console) section,
+[`$debugging`](#variable.debugging) and
+[`$smarty_debug_id`](#variable.smarty.debug.id).

docs/programmers/api-variables/variable-debugging.md

@@ -0,0 +1,17 @@
+\$debugging {#variable.debugging}
+===========
+
+This enables the [debugging console](#chapter.debugging.console). The
+console is a javascript popup window that informs you of the
+[included](#language.function.include) templates, variables
+[assigned](#api.assign) from php and [config file
+variables](#language.config.variables) for the current script. It does
+not show variables assigned within a template with the
+[`{assign}`](#language.function.assign) function.
+
+The console can also be enabled from the url with
+[`$debugging_ctrl`](#variable.debugging.ctrl).
+
+See also [`{debug}`](#language.function.debug),
+[`$debug_tpl`](#variable.debug_template), and
+[`$debugging_ctrl`](#variable.debugging.ctrl).

docs/programmers/api-variables/variable-default-config-handler-func.md

@@ -0,0 +1,50 @@
+\$default\_config\_handler\_func {#variable.default.config.handler.func}
+================================
+
+This function is called when a config file cannot be obtained from its
+resource.
+
+> **Note**
+>
+> The default handler is currently only invoked for file resources. It
+> is not triggered when the resource itself cannot be found, in which
+> case a SmartyException is thrown.
+
+
+    <?php
+
+    $smarty = new Smarty();
+    $smarty->default_config_handler_func = 'my_default_config_handler_func';
+
+    /**
+     * Default Config Handler
+     *
+     * called when Smarty's file: resource is unable to load a requested file
+     * 
+     * @param string   $type     resource type (e.g. "file", "string", "eval", "resource")
+     * @param string   $name     resource name (e.g. "foo/bar.tpl")
+     * @param string  &$content  config's content
+     * @param integer &$modified config's modification time
+     * @param Smarty   $smarty   Smarty instance
+     * @return string|boolean   path to file or boolean true if $content and $modified 
+     *                          have been filled, boolean false if no default config 
+     *                          could be loaded
+     */
+    function my_default_config_handler_func($type, $name, &$content, &$modified, Smarty $smarty) {
+        if (false) {
+            // return corrected filepath
+            return "/tmp/some/foobar.tpl";
+        } elseif (false) {
+            // return a config directly
+            $content = 'someVar = "the config source"';
+            $modified = time();
+            return true;
+        } else {
+            // tell smarty that we failed
+            return false;
+        }
+    }
+
+    ?>
+
+      

docs/programmers/api-variables/variable-default-config-type.md

@@ -0,0 +1,7 @@
+\$default\_config\_type {#variable.default.config.type}
+=======================
+
+This tells smarty what resource type to use for config files. The
+default value is `file`, meaning that `$smarty->configLoad('test.conf')`
+and `$smarty->configLoad('file:test.conf')` are identical in meaning.
+See the [resource](#resources) chapter for more details.

docs/programmers/api-variables/variable-default-modifiers.md

@@ -0,0 +1,8 @@
+\$default\_modifiers {#variable.default.modifiers}
+====================
+
+This is an array of modifiers to implicitly apply to every variable in a
+template. For example, to HTML-escape every variable by default, use
+`array('escape:"htmlall"')`. To make a variable exempt from default
+modifiers, add the \'nofilter\' attribute to the output tag such as
+`{$var nofilter}`.

docs/programmers/api-variables/variable-default-resource-type.md

@@ -0,0 +1,7 @@
+\$default\_resource\_type {#variable.default.resource.type}
+=========================
+
+This tells smarty what resource type to use implicitly. The default
+value is `file`, meaning that `$smarty->display('index.tpl')` and
+`$smarty->display('file:index.tpl')` are identical in meaning. See the
+[resource](#resources) chapter for more details.

docs/programmers/api-variables/variable-default-template-handler-func.md

@@ -0,0 +1,50 @@
+\$default\_template\_handler\_func {#variable.default.template.handler.func}
+==================================
+
+This function is called when a template cannot be obtained from its
+resource.
+
+> **Note**
+>
+> The default handler is currently only invoked for file resources. It
+> is not triggered when the resource itself cannot be found, in which
+> case a SmartyException is thrown.
+
+
+    <?php
+
+    $smarty = new Smarty();
+    $smarty->default_template_handler_func = 'my_default_template_handler_func';
+
+    /**
+     * Default Template Handler
+     *
+     * called when Smarty's file: resource is unable to load a requested file
+     * 
+     * @param string   $type     resource type (e.g. "file", "string", "eval", "resource")
+     * @param string   $name     resource name (e.g. "foo/bar.tpl")
+     * @param string  &$content  template's content
+     * @param integer &$modified template's modification time
+     * @param Smarty   $smarty   Smarty instance
+     * @return string|boolean   path to file or boolean true if $content and $modified 
+     *                          have been filled, boolean false if no default template 
+     *                          could be loaded
+     */
+    function my_default_template_handler_func($type, $name, &$content, &$modified, Smarty $smarty) {
+        if (false) {
+            // return corrected filepath
+            return "/tmp/some/foobar.tpl";
+        } elseif (false) {
+            // return a template directly
+            $content = "the template source";
+            $modified = time();
+            return true;
+        } else {
+            // tell smarty that we failed
+            return false;
+        }
+    }
+
+    ?>
+
+      

docs/programmers/api-variables/variable-direct-access-security.md

@@ -0,0 +1,13 @@
+\$direct\_access\_security {#variable.direct.access.security}
+==========================
+
+Direct access security inhibits direct browser access to compiled or
+cached template files.
+
+Direct access security is enabled by default. To disable it set
+`$direct_access_security` to FALSE.
+
+> **Note**
+>
+> This is a compile time option. If you change the setting you must make
+> sure that the templates get recompiled.

docs/programmers/api-variables/variable-error-reporting.md

@@ -0,0 +1,17 @@
+\$error\_reporting {#variable.error.reporting}
+==================
+
+When this value is set to a non-null-value it\'s value is used as php\'s
+[`error_reporting`](&url.php-manual;error_reporting) level inside of
+[`display()`](#api.display) and [`fetch()`](#api.fetch).
+
+Smarty 3.1.2 introduced the
+[`muteExpectedErrors()`](#api.mute.expected.errors) function. Calling
+`Smarty::muteExpectedErrors();` after setting up custom error handling
+will ensure that warnings and notices (deliberately) produced by Smarty
+will not be passed to other custom error handlers. If your error logs
+are filling up with warnings regarding `filemtime()` or `unlink()`
+calls, please enable Smarty\'s error muting.
+
+See also [debugging](#chapter.debugging.console) and
+[troubleshooting](#troubleshooting).

docs/programmers/api-variables/variable-escape-html.md

@@ -0,0 +1,21 @@
+\$escape\_html {#variable.escape.html}
+==============
+
+Setting `$escape_html` to TRUE will escape all template variable output
+by wrapping it in
+`htmlspecialchars({$output}, ENT_QUOTES, SMARTY_RESOURCE_CHAR_SET);`,
+which is the same as `{$variable|escape:"html"}`.
+
+Template designers can choose to selectively disable this feature by
+adding the `nofilter` flag: `{$variable nofilter}`.
+
+Modifiers and Filters are run in the following order: modifier,
+default\_modifier, \$escape\_html, registered variable filters,
+autoloaded variable filters, template instance\'s variable filters.
+Everything except the individual modifier can be disabled with the
+`nofilter` flag.
+
+> **Note**
+>
+> This is a compile time option. If you change the setting you must make
+> sure that the templates get recompiled.

docs/programmers/api-variables/variable-force-cache.md

@@ -0,0 +1,6 @@
+\$force\_cache {#variable.force.cache}
+==============
+
+This forces Smarty to (re)cache templates on every invocation. It does
+not override the [`$caching`](#variable.caching) level, but merely
+pretends the template has never been cached before.

docs/programmers/api-variables/variable-force-compile.md

@@ -0,0 +1,9 @@
+\$force\_compile {#variable.force.compile}
+================
+
+This forces Smarty to (re)compile templates on every invocation. This
+setting overrides [`$compile_check`](#variable.compile.check). By
+default this is FALSE. This is handy for development and
+[debugging](#chapter.debugging.console). It should never be used in a
+production environment. If [`$caching`](#variable.caching) is enabled,
+the cache file(s) will be regenerated every time.

docs/programmers/api-variables/variable-left-delimiter.md

@@ -0,0 +1,8 @@
+\$left\_delimiter {#variable.left.delimiter}
+=================
+
+This is the left delimiter used by the template language. Default is
+`{`.
+
+See also [`$right_delimiter`](#variable.right.delimiter) and [escaping
+smarty parsing](#language.escaping) .

docs/programmers/api-variables/variable-locking-timeout.md

@@ -0,0 +1,7 @@
+\$locking\_timeout {#variable.locking.timeout}
+==================
+
+This is maximum time in seconds a cache lock is valid to avoid dead
+locks. The deafult value is 10 seconds.
+
+See also [`$cache_locking`](#variable.cache.locking)

docs/programmers/api-variables/variable-merge-compiled-includes.md

@@ -0,0 +1,27 @@
+\$merge\_compiled\_includes {#variable.merge.compiled.includes}
+===========================
+
+By setting `$merge_compiled_includes` to TRUE Smarty will merge the
+compiled template code of subtemplates into the compiled code of the
+main template. This increases rendering speed of templates using a many
+different sub-templates.
+
+Individual sub-templates can be merged by setting the `inline` option
+flag within the `{include}` tag. `$merge_compiled_includes` does not
+have to be enabled for the `inline` merge.
+
+::: {.informalexample}
+
+    <?php
+    $smarty->merge_compiled_includes = true;
+    ?>
+
+            
+:::
+
+> **Note**
+>
+> This is a compile time option. If you change the setting you must make
+> sure that the templates get recompiled.
+
+See also [`{include}`](#language.function.include) tag

docs/programmers/api-variables/variable-php-handling.md

@@ -0,0 +1,21 @@
+\$php\_handling {#variable.php.handling}
+===============
+
+This tells Smarty how to handle PHP code embedded in the templates.
+There are four possible settings, the default being
+`Smarty::PHP_PASSTHRU`. Note that this does NOT affect php code within
+[`{php}{/php}`](#language.function.php) tags in the template.
+
+-   `Smarty::PHP_PASSTHRU` - Smarty echos tags as-is.
+
+-   `Smarty::PHP_QUOTE` - Smarty quotes the tags as html entities.
+
+-   `Smarty::PHP_REMOVE` - Smarty removes the tags from the templates.
+
+-   `Smarty::PHP_ALLOW` - Smarty will execute the tags as PHP code.
+
+> **Note**
+>
+> Embedding PHP code into templates is highly discouraged. Use [custom
+> functions](#plugins.functions) or [modifiers](#plugins.modifiers)
+> instead.

docs/programmers/api-variables/variable-plugins-dir.md

@@ -0,0 +1,28 @@
+\$plugins\_dir {#variable.plugins.dir}
+==============
+
+This is the directory or directories where Smarty will look for the
+plugins that it needs. Default is `plugins/` under the
+[`SMARTY_DIR`](#constant.smarty.dir). If you supply a relative path,
+Smarty will first look under the [`SMARTY_DIR`](#constant.smarty.dir),
+then relative to the current working directory, then relative to the PHP
+include\_path. If `$plugins_dir` is an array of directories, Smarty will
+search for your plugin in each plugin directory **in the order they are
+given**.
+
+> **Note**
+>
+> For best performance, do not setup your `$plugins_dir` to have to use
+> the PHP include path. Use an absolute pathname, or a path relative to
+> `SMARTY_DIR` or the current working directory.
+
+> **Note**
+>
+> As of Smarty 3.1 the attribute \$plugins\_dir is no longer accessible
+> directly. Use [`getPluginsDir()`](#api.get.plugins.dir),
+> [`setPluginsDir()`](#api.set.plugins.dir) and
+> [`addPluginsDir()`](#api.add.plugins.dir) instead.
+
+See also [`getPluginsDir()`](#api.get.plugins.dir),
+[`setPluginsDir()`](#api.set.plugins.dir) and
+[`addPluginsDir()`](#api.add.plugins.dir).

docs/programmers/api-variables/variable-right-delimiter.md

@@ -0,0 +1,8 @@
+\$right\_delimiter {#variable.right.delimiter}
+==================
+
+This is the right delimiter used by the template language. Default is
+`}`.
+
+See also [`$left_delimiter`](#variable.left.delimiter) and [escaping
+smarty parsing](#language.escaping).

docs/programmers/api-variables/variable-smarty-debug-id.md

@@ -0,0 +1,9 @@
+\$smarty\_debug\_id {#variable.smarty.debug.id}
+===================
+
+The value of `$smarty_debug_id` defines the URL keyword to enable
+debugging at browser level. The default value is `SMARTY_DEBUG`.
+
+See also [debugging console](#chapter.debugging.console) section,
+[`$debugging`](#variable.debugging) and
+[`$debugging_ctrl`](#variable.debugging.ctrl).

docs/programmers/api-variables/variable-template-dir.md

@@ -0,0 +1,36 @@
+\$template\_dir {#variable.template.dir}
+===============
+
+This is the name of the default template directory. If you do not supply
+a resource type when including files, they will be found here. By
+default this is `./templates`, meaning that Smarty will look for the
+`templates/` directory in the same directory as the executing php
+script. \$template\_dir can also be an array of directory paths: Smarty
+will traverse the directories and stop on the first matching template
+found.
+
+> **Note**
+>
+> It is not recommended to put this directory under the web server
+> document root.
+
+> **Note**
+>
+> If the directories known to `$template_dir` are relative to
+> directories known to the
+> [include\_path](&url.php-manual;ini.core.php#ini.include-path) you
+> need to activate the [`$use_include_path`](#variable.use.include.path)
+> option.
+
+> **Note**
+>
+> As of Smarty 3.1 the attribute \$template\_dir is no longer accessible
+> directly. Use [`getTemplateDir()`](#api.get.template.dir),
+> [`setTemplateDir()`](#api.set.template.dir) and
+> [`addTemplateDir()`](#api.add.template.dir) instead.
+
+See also [`Template Resources`](#resources),
+[`$use_include_path`](#variable.use.include.path),
+[`getTemplateDir()`](#api.get.template.dir),
+[`setTemplateDir()`](#api.set.template.dir) and
+[`addTemplateDir()`](#api.add.template.dir).

docs/programmers/api-variables/variable-trusted-dir.md

@@ -0,0 +1,8 @@
+\$trusted\_dir {#variable.trusted.dir}
+==============
+
+`$trusted_dir` is only for use when security is enabled. This is an
+array of all directories that are considered trusted. Trusted
+directories are where you keep php scripts that are executed directly
+from the templates with
+[`{include_php}`](#language.function.include.php).

docs/programmers/api-variables/variable-use-include-path.md

@@ -0,0 +1,49 @@
+\$use\_include\_path {#variable.use.include.path}
+====================
+
+This tells smarty to respect the
+[include\_path](&url.php-manual;ini.core.php#ini.include-path) within
+the [`File Template Resource`](#resources.file) handler and the plugin
+loader to resolve the directories known to
+[`$template_dir`](#variable.template.dir). The flag also makes the
+plugin loader check the include\_path for
+[`$plugins_dir`](#variable.plugins.dir).
+
+> **Note**
+>
+> You should not design your applications to rely on the include\_path,
+> as this may - depending on your implementation - slow down your system
+> (and Smarty) considerably.
+
+If use\_include\_path is enabled, file discovery for
+[`$template_dir`](#variable.template.dir) and
+[`$plugins_dir`](#variable.plugins.dir) work as follows.
+
+-   For each element `$directory` in array (\$template\_dir or
+    \$plugins\_dir) do
+
+-   Test if requested file is in `$directory` relative to the [current
+    working directory](&url.php-manual;function.getcwd.php). If file
+    found, return it.
+
+-   For each `$path` in include\_path do
+
+-   Test if requested file is in `$directory` relative to the `$path`
+    (possibly relative to the [current working
+    directory](&url.php-manual;function.getcwd.php)). If file found,
+    return it.
+
+-   Try default\_handler or fail.
+
+This means that whenever a directory/file relative to the current
+working directory is encountered, it is preferred over anything
+potentially accessible through the include\_path.
+
+> **Note**
+>
+> Smarty does not filter elements of the include\_path. That means a
+> \".:\" within your include path will trigger the current working
+> directory lookup twice.
+
+See also [`Template Resources`](#resources) and
+[`$template_dir`](#variable.template.dir)

docs/programmers/api-variables/variable-use-sub-dirs.md

@@ -0,0 +1,31 @@
+\$use\_sub\_dirs {#variable.use.sub.dirs}
+================
+
+Smarty will create subdirectories under the [compiled
+templates](#variable.compile.dir) and [cache](#variable.cache.dir)
+directories if `$use_sub_dirs` is set to TRUE, default is FALSE. In an
+environment where there are potentially tens of thousands of files
+created, this may help the filesystem speed. On the other hand, some
+environments do not allow PHP processes to create directories, so this
+must be disabled which is the default.
+
+Sub directories are more efficient, so use them if you can.
+Theoretically you get much better perfomance on a filesystem with 10
+directories each having 100 files, than with 1 directory having 1000
+files. This was certainly the case with Solaris 7 (UFS)\... with newer
+filesystems such as ext3 and especially reiserfs, the difference is
+almost nothing.
+
+> **Note**
+>
+> -   `$use_sub_dirs=true` doesn\'t work with
+>     [safe\_mode=On](&url.php-manual;features.safe-mode), that\'s why
+>     it\'s switchable and why it\'s off by default.
+>
+> -   `$use_sub_dirs=true` on Windows can cause problems.
+>
+> -   Safe\_mode is being deprecated in PHP6.
+>
+See also [`$compile_id`](#variable.compile.id),
+[`$cache_dir`](#variable.cache.dir), and
+[`$compile_dir`](#variable.compile.dir).