Further WIP improving docs

docs/api/basics.md

@@ -0,0 +1,92 @@
+# Basics
+
+## Installation
+For installation instructies, please see the [getting started section](../getting-started.md).
+
+## Rendering a template
+Here's how you create an instance of Smarty in your PHP scripts:
+```php
+<?php
+
+require 'vendor/autoload.php';
+use Smarty\Smarty;
+$smarty = new Smarty();
+```
+
+You now have a Smarty object that you can use to render templates.
+
+```php
+<?php
+
+require 'vendor/autoload.php';
+use Smarty\Smarty;
+$smarty = new Smarty();
+
+$smarty->display('string:The current smarty version is: {$smarty.version}.');
+// or 
+echo $smarty->fetch('string:The current smarty version is: {$smarty.version}.');
+```
+
+## Using file-based templates
+You probably want to manage your templates as files. Create a subdirectory called 'templates' and
+then configure Smarty to use that:
+
+```php
+<?php
+
+require 'vendor/autoload.php';
+use Smarty\Smarty;
+$smarty = new Smarty();
+
+$smarty->setTemplateDir(__DIR__ . '/templates');
+```
+
+Say you have a template file called 'version.tpl', stored in the 'templates' directory like this:
+```smarty
+<h1>Hi</h1>
+The current smarty version is: {$smarty.version|escape}.
+```
+
+You can now render this, using:
+```php
+<?php
+
+require 'vendor/autoload.php';
+use Smarty\Smarty;
+$smarty = new Smarty();
+
+$smarty->setTemplateDir(__DIR__ . '/templates');
+$smarty->display('version.tpl');
+```
+
+## Assigning variables
+
+Templates start to become really useful once you add variables to the mix.
+
+Create a template called 'footer.tpl' in the 'templates' directory like this:
+```smarty
+<small>Copyright {$companyName|escape}</small>
+```
+
+Now assign a value to the 'companyName' variable and render your template like this:
+
+```php
+<?php
+
+require 'vendor/autoload.php';
+use Smarty\Smarty;
+$smarty = new Smarty();
+
+$smarty->setTemplateDir(__DIR__ . '/templates');
+$smarty->assign('companyName', 'AC & ME Corp.');
+$smarty->display('footer.tpl');
+```
+
+Run this, and you will see:
+
+```html
+<small>Copyright AC &amp; ME Corp.</small>
+```
+
+Note how the [escape modifier](../designers/language-modifiers/language-modifier-escape.md) 
+translated the `&` character into the proper HTML syntax `&amp;`.

docs/api/configuring.md

@@ -0,0 +1,158 @@
+# Configuring Smarty
+
+## Setting the template path
+By default, Smarty looks for templates to render in `./templates`.
+
+You can change this, or even use multiple paths to use when looking for templates.
+
+If you need to change this, you can use `setTemplateDir()` or `addTemplateDir()`.
+Use `getTemplateDir()` to retrieve the configured paths.
+
+```php
+<?php
+
+ // set a single directory where the config files are stored
+$smarty->setTemplateDir('./config');
+
+// set multiple directories where config files are stored
+$smarty->setTemplateDir(['./config', './config_2', './config_3']);
+
+// add directory where config files are stored to the current list of dirs
+$smarty->addTemplateDir('./config_1');
+
+// add multiple directories to the current list of dirs
+$smarty->addTemplateDir([
+    './config_2',
+    './config_3',
+]);
+
+// chaining of method calls
+$smarty->setTemplateDir('./config')
+       ->addTemplateDir('./config_1')
+       ->addTemplateDir('./config_2');
+
+// get all directories where config files are stored
+$template_dirs = $smarty->getTemplateDir();
+var_dump($template_dirs); // array
+
+// get directory identified by key
+$template_dir = $smarty->getTemplateDir(0);
+var_dump($template_dir); // string
+```
+
+## Setting the path for compiled templates
+Smarty compiles templates to native PHP to be as fast as possible.
+The default path where these PHP-files are stored is `./templates_c`.
+
+If you need to change this, you can use `setCompileDir()`.
+Use `getCompileDir()` to retrieve the configured path.
+
+```php
+<?php
+
+// set another path to store compiled templates
+$smarty->setCompileDir('/data/compiled_templates');
+
+// get directory where compiled templates are stored
+$compileDir = $smarty->getCompileDir();
+```
+
+
+## Setting the config path
+Smarty can [load data from config files](./variables/config-files.md).
+By default, Smarty loads the config files from `./configs`.
+
+You can change this, or even use multiple paths to use when looking for config files.
+
+If you need to change this, you can use `setConfigDir()` or `addConfigDir()`.
+Use `getConfigDir()` to retrieve the configured paths.
+
+```php
+<?php
+
+ // set a single directory where the config files are stored
+$smarty->setConfigDir('./config');
+
+// set multiple directories where config files are stored
+$smarty->setConfigDir(['./config', './config_2', './config_3']);
+
+// add directory where config files are stored to the current list of dirs
+$smarty->addConfigDir('./config_1');
+
+// add multiple directories to the current list of dirs
+$smarty->addConfigDir([
+    './config_2',
+    './config_3',
+]);
+
+// chaining of method calls
+$smarty->setConfigDir('./config')
+       ->addConfigDir('./config_1', 'one')
+       ->addConfigDir('./config_2', 'two');
+
+// get all directories where config files are stored
+$config_dirs = $smarty->getConfigDir();
+var_dump($config_dirs); // array
+
+// get directory identified by key
+$config_dir = $smarty->getConfigDir(0);
+var_dump($config_dir); // string
+```
+
+## Setting the path for caches
+Even though Smarty runs templates as native PHP for maximum speed, it still needs to 
+execute the PHP code on each call. If your data doesn't change all that often, you
+may be able to speed up your application even more by using output caching.
+
+Output caching can be a tricky subject, so we devoted an entire [section to caching](./caching/basics.md).
+Be sure to read that if you want to use caching.
+
+By default, Smarty stores caches to PHP-files in a subdirectory named `./cache`.
+
+If you need to change this, you can use `setCacheDir()`.
+Use `getCacheDir()` to retrieve the configured path.
+
+```php
+<?php
+
+// set another path to store caches
+$smarty->setCacheDir('/data/caches');
+
+// get directory where cached templates are stored
+$cacheDir = $smarty->getCacheDir();
+```
+
+## Charset encoding
+
+There are a variety of encodings for textual data, ISO-8859-1 (Latin1)
+and UTF-8 being the most popular. Unless you change `\Smarty\Smarty::$_CHARSET`,
+Smarty recognizes `UTF-8` as the internal charset.
+
+> **Note**
+>
+> `ISO-8859-1` has been PHP\'s default internal charset since the
+> beginning. Unicode has been evolving since 1991. Since then, it has
+> become the one charset to conquer them all, as it is capable of
+> encoding most of the known characters even across different character
+> systems (latin, cyrillic, japanese, ...). `UTF-8` is unicode\'s most
+> used encoding, as it allows referencing the thousands of character
+> with the smallest size overhead possible.
+>
+> Since unicode and UTF-8 are very widespread nowadays, their use is
+> strongly encouraged.
+
+> **Note**
+>
+> Smarty\'s internals and core plugins are truly UTF-8 compatible since
+> Smarty 3.1.
+
+```php
+<?php
+    
+// use japanese character encoding
+mb_internal_charset('EUC-JP');
+
+\Smarty\Smarty::$_CHARSET = 'EUC-JP';
+$smarty = new \Smarty\Smarty();
+```
+