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();
+```
+     

docs/appendixes/tips.md

@@ -209,8 +209,7 @@ fetching the data up front?
 You can do this by writing a custom plugin for fetching the content and
 assigning it to a template variable.
 
-`function.load_ticker.php` - drop file in
-[`$plugins directory`](../programmers/api-variables/variable-plugins-dir.md)
+`function.load_ticker.php`
 
 ```php
 

docs/designers/language-modifiers/index.md

@@ -97,7 +97,7 @@ These parameters follow the modifier name and are separated by a `:`
     > `{(8+2)|count_characters}`.
 
 - Custom modifiers can be registered
-    with the [`registerPlugin()`](../programmers/api-functions/api-register-plugin.md)
+    with the [`registerPlugin()`](../../programmers/api-functions/api-register-plugin.md)
     function.
 
 See also [`registerPlugin()`](../../programmers/api-functions/api-register-plugin.md), [combining

docs/designers/language-modifiers/language-modifier-from-charset.md

@@ -16,5 +16,5 @@ modifier](language-modifier-to-charset.md).
 > modifier should only be used in cases where the application cannot
 > anticipate that a certain string is required in another encoding.
 
-See also [Charset Encoding](../../programmers/charset.md), [to_charset
+See also [Configuring Smarty](../../api/configuring.md), [to_charset
 modifier](language-modifier-to-charset.md).

docs/designers/language-modifiers/language-modifier-to-charset.md

@@ -16,5 +16,5 @@ modifier](#language.modifier.from_charset).
 > modifier should only be used in cases where the application cannot
 > anticipate that a certain string is required in another encoding.
 
-See also [Charset Encoding](../../programmers/charset.md), [from_charset
+See also [Configuring Smarty](../../api/configuring.md), [from_charset
 modifier](language-modifier-from-charset.md).

docs/designers/language-variables/language-variables-smarty.md

@@ -66,8 +66,7 @@ difference.
 
 ## {$smarty.const}
 
-You can access PHP constant values directly. See also [smarty
-constants](../../programmers/smarty-constants.md).
+You can access PHP constant values directly.
 
 ```php
 <?php

docs/index.md

@@ -20,30 +20,11 @@ and 480 for $height, the result is:
 </p>
 ```
 
-## Introduction
+## Getting Started
+- [Getting Started](./getting-started.md)
 - [Philosophy](./philosophy.md) - or "Why do I need a template engine?"
 - [Features](./features.md) - or "Why do I want Smarty?"
-- [Getting Started](./getting-started.md)
-
-## Smarty for template designers
-- [Basic Syntax](designers/language-basic-syntax/index.md)
-- [Variables](designers/language-variables/index.md)
-- [Variable Modifiers](designers/language-modifiers/index.md)
-- [Combining Modifiers](./designers/language-combining-modifiers.md)
-- [Built-in Functions](designers/language-builtin-functions/index.md)
-- [Custom Functions](designers/language-custom-functions/index.md)
-- [Config Files](./designers/config-files.md)
-- [Debugging Console](./designers/chapter-debugging-console.md)
-
-## Smarty for php developers
-- [Charset Encoding](./programmers/charset.md)
-- [Smarty Class Variables](./programmers/api-variables.md)
-- [Smarty Class Methods](./programmers/api-functions.md)
-- [Caching](./programmers/caching.md)
-- [Resources](./programmers/resources.md)
-- [Advanced Features](./programmers/advanced-features.md)
-- [Extending Smarty With Plugins](./programmers/plugins.md)
 
-## Other
+## Help
 - [Some random tips & tricks](./appendixes/tips.md)
 - [Troubleshooting](./appendixes/troubleshooting.md)