Reformat documentation

README.md

@@ -9,7 +9,7 @@ Fenom - Template Engine for PHP
 [![Coverage Status](https://coveralls.io/repos/bzick/fenom/badge.png?branch=master)](https://coveralls.io/r/bzick/fenom?branch=master)
 [![Code Climate](https://codeclimate.com/github/bzick/fenom.png)](https://codeclimate.com/github/bzick/fenom)
 [![Total Downloads](https://poser.pugx.org/fenom/fenom/downloads.png)](https://packagist.org/packages/fenom/fenom)
-## [Quick start](./docs/start.md) :: [Documentation](./docs/readme.md) :: [Benchmark](./docs/benchmark.md)
+## [Quick start](./docs/en/start.md) :: [Documentation](./docs/readme.md) [en](./docs/en/readme.md)/[ru](./docs/ru/readme.md) :: [Benchmark](./docs/en/benchmark.md)
 <!-- :: [Articles](./docs/articles.md) -->
 
 ### What is it
@@ -18,13 +18,13 @@ Fenom - Template Engine for PHP
 
 It means:
 
-* Known Smarty-like [syntax](./docs/syntax.md) with improvements. 
+* Known Smarty-like [syntax](./docs/en/syntax.md) with improvements.
-* Very [fast](./docs/benchmark.md).
+* Very [fast](./docs/en/benchmark.md).
-* [Lightweight](./docs/benchmark.md).
+* [Lightweight](./docs/en/benchmark.md).
-* Very [flexible](./docs/configuration.md#extends).
+* Very [flexible](./docs/en/configuration.md#extends).
 * Progressive parser without regular expressions.
 * High [code coverage](https://coveralls.io/r/bzick/fenom?branch=master).
-* Easy to understand [how it works](./docs/dev/readme.md).
+* Easy to understand [how it works](./docs/en/dev/readme.md).
-* Easy to [use](./docs/start.md).
+* Easy to [use](./docs/en/start.md).
-* Maximum [protection](./docs/configuration.md#configure).
+* Maximum [protection](./docs/en/configuration.md#configure).
 

docs/en/readme.md

@@ -0,0 +1,86 @@
+Documentation
+=============
+
+**Please, help translate documentation to english or fix typos. [Read more](./helpme.md).**
+
+### Fenom
+
+* [Quick start](./start.md)
+* [Usage](./start.md#install-fenom)
+* [Framework adapters](./adapters.md)
+* [For developers](./dev/readme.md)
+* [Configuration](./configuration.md)
+* [Syntax](./syntax.md)
+* [Operators](./operators.md)
+
+***
+
+### Tags
+
+[Usage](./syntax.md#tags)
+
+* [var](./tags/var.md) — define variable
+* [if](./tags/if.md), `elseif` and `else` — conditional statement
+* [foreach](./tags/foreach.md), `foreaelse`, `break` and `continue` — traversing items in an array or object
+* [for](./tags/for.md), `forelse`, `break` and `continue` — loop statement
+* [switch](./tags/switch.md), `case`, `default` —
+* [cycle](./tags/cycle.md) — cycles on an array of values
+* [include](./tags/include.md), `insert` —  includes and evaluates the specified template
+* [extends](./tags/extends.md), `use`, `block` and `parent` — template inheritance
+* [filter](./tags/filter.md) — apply modifier on a block of template data
+* [ignore](./tags/ignore.md) — ignore Fenom syntax
+* [macro](./tags/macro.md) and `import` — template functions
+* [autoescape](./tags/autoescape.md) — escape template fragment
+* [raw](./tags/raw.md) — unescape template fragment
+* [unset](./tags/unset.md) — unset a given variables
+* or [add](./ext/extend.md#add-tags) yours
+
+
+***
+
+### Modifiers
+
+[Usage](./syntax.md#modifiers)
+
+* [upper](./mods/upper.md) aka `up` — convert to uppercase a string
+* [lower](./mods/lower.md) aka `low` — convert to lowercase a string
+* [date_format](./mods/date_format.md) - format date, timestamp via strftime() function
+* [date](./mods/date.md) - format date, timestamp via date() function
+* [truncate](./mods/truncate.md) — truncate thee string to specified length
+* [escape](./mods/escape.md) aka `e` — escape the string
+* [unescape](./mods/unescape.md) — unescape the string
+* [strip](./mods/strip.md) — remove extra whitespaces
+* [length](./mods/length.md) — calculate length of string, array, object
+* [in](./mods/in.md) — find value in string or array
+* [match](./mods/match.md) — match string against a pattern.
+* [ematch](./mods/ematch.md) — perform a regular expression match.
+* [replace](./mods/replace.md) — replace all occurrences of the search string with the replacement string.
+* [ereplace](./mods/ereplace.md) — perform a regular expression search and replace.
+* [split](./mods/split.md) — split a string by string.
+* [esplit](./mods/esplit.md) — split string by a regular expression.
+* [join](./mods/join.md) — join array elements with a string.
+* allowed functions: `json_encode`, `json_decode`, `count`, `is_string`, `is_array`, `is_numeric`, `is_int`, `is_object`,
+`strtotime`, `gettype`, `is_double`, `ip2long`, `long2ip`, `strip_tags`, `nl2br`
+* or [add](./ext/extend.md#add-modifiers) yours
+
+***
+
+### Operators
+
+* [Arithmetic operators](./operators.md#arithmetic-operators) — `+`, `-`, `*`, `/`, `%`
+* [Logical operators](./operators.md#logical-operators) — `||`, `&&`, `!$var`, `and`, `or`, `xor`
+* [Comparison operators](./operators.md#comparison-operators) — `>`, `>=`, `<`, `<=`, `==`, `!=`, `!==`, `<>`
+* [Bitwise operators](./operators.md#bitwise-operators) — `|`, `&`, `^`, `~$var`, `>>`, `<<`
+* [Assignment operators](./operators.md#assignment-operators) — `=`, `+=`, `-=`, `*=`, `/=`, `%=`, `&=`, `|=`, `^=`, `>>=`, `<<=`
+* [String concatenation operator](./operators.md#string-operator) — `$str1 ~ $str2`
+* [Ternary operators](./operators.md#ternary-operators) — `$a ? $b : $c`, `$a ! $b : $c`, `$a ?: $c`, `$a !: $c`
+* [Check operators](./operators.md#check-operators) — `$var?`, `$var!`
+* [Test operator](./operators.md#test-operator) — `is`, `is not`
+* [Containment operator](./operators.md#containment-operator) — `in`, `not in`
+
+***
+
+### Extends
+
+* [Extend Fenom](./ext/extend.md)
+* [Add-ons](./ext/extensions.md)

docs/readme.md

@@ -1,86 +1,5 @@
-Documentation
+Languages
-=============
+=========
 
-**Please, help translate documentation to english or fix typos. [Read more](./helpme.md).**
+* [English](./en/readme.md)
-
+* [Russian](./ru/readme.md)
-### Fenom
-
-* [Quick start](./start.md)
-* [Usage](./start.md#install-fenom)
-* [Framework adapters](./adapters.md)
-* [For developers](./dev/readme.md)
-* [Configuration](./configuration.md)
-* [Syntax](./syntax.md)
-* [Operators](./operators.md)
-
-***
-
-### Tags
-
-[Usage](./syntax.md#tags)
-
-* [var](./tags/var.md) — define variable
-* [if](./tags/if.md), `elseif` and `else` — conditional statement
-* [foreach](./tags/foreach.md), `foreaelse`, `break` and `continue` — traversing items in an array or object
-* [for](./tags/for.md), `forelse`, `break` and `continue` — loop statement
-* [switch](./tags/switch.md), `case`, `default` —
-* [cycle](./tags/cycle.md) — cycles on an array of values
-* [include](./tags/include.md), `insert` —  includes and evaluates the specified template
-* [extends](./tags/extends.md), `use`, `block` and `parent` — template inheritance
-* [filter](./tags/filter.md) — apply modifier on a block of template data
-* [ignore](./tags/ignore.md) — ignore Fenom syntax
-* [macro](./tags/macro.md) and `import` — template functions
-* [autoescape](./tags/autoescape.md) — escape template fragment
-* [raw](./tags/raw.md) — unescape template fragment
-* [unset](./tags/unset.md) — unset a given variables
-* or [add](./ext/extend.md#add-tags) yours
-
-
-***
-
-### Modifiers
-
-[Usage](./syntax.md#modifiers)
-
-* [upper](./mods/upper.md) aka `up` — convert to uppercase a string
-* [lower](./mods/lower.md) aka `low` — convert to lowercase a string
-* [date_format](./mods/date_format.md) - format date, timestamp via strftime() function
-* [date](./mods/date.md) - format date, timestamp via date() function
-* [truncate](./mods/truncate.md) — truncate thee string to specified length
-* [escape](./mods/escape.md) aka `e` — escape the string
-* [unescape](./mods/unescape.md) — unescape the string
-* [strip](./mods/strip.md) — remove extra whitespaces
-* [length](./mods/length.md) — calculate length of string, array, object
-* [in](./mods/in.md) — find value in string or array
-* [match](./mods/match.md) — match string against a pattern.
-* [ematch](./mods/ematch.md) — perform a regular expression match.
-* [replace](./mods/replace.md) — replace all occurrences of the search string with the replacement string.
-* [ereplace](./mods/ereplace.md) — perform a regular expression search and replace.
-* [split](./mods/split.md) — split a string by string.
-* [esplit](./mods/esplit.md) — split string by a regular expression.
-* [join](./mods/join.md) — join array elements with a string.
-* allowed functions: `json_encode`, `json_decode`, `count`, `is_string`, `is_array`, `is_numeric`, `is_int`, `is_object`,
-`strtotime`, `gettype`, `is_double`, `ip2long`, `long2ip`, `strip_tags`, `nl2br`
-* or [add](./ext/extend.md#add-modifiers) yours
-
-***
-
-### Operators
-
-* [Arithmetic operators](./operators.md#arithmetic-operators) — `+`, `-`, `*`, `/`, `%`
-* [Logical operators](./operators.md#logical-operators) — `||`, `&&`, `!$var`, `and`, `or`, `xor`
-* [Comparison operators](./operators.md#comparison-operators) — `>`, `>=`, `<`, `<=`, `==`, `!=`, `!==`, `<>`
-* [Bitwise operators](./operators.md#bitwise-operators) — `|`, `&`, `^`, `~$var`, `>>`, `<<`
-* [Assignment operators](./operators.md#assignment-operators) — `=`, `+=`, `-=`, `*=`, `/=`, `%=`, `&=`, `|=`, `^=`, `>>=`, `<<=`
-* [String concatenation operator](./operators.md#string-operator) — `$str1 ~ $str2`
-* [Ternary operators](./operators.md#ternary-operators) — `$a ? $b : $c`, `$a ! $b : $c`, `$a ?: $c`, `$a !: $c`
-* [Check operators](./operators.md#check-operators) — `$var?`, `$var!`
-* [Test operator](./operators.md#test-operator) — `is`, `is not`
-* [Containment operator](./operators.md#containment-operator) — `in`, `not in`
-
-***
-
-### Extends
-
-* [Extend Fenom](./ext/extend.md)
-* [Add-ons](./ext/extensions.md)

docs/ru/adapters.md

@@ -1,8 +1,8 @@
-Adapters
+Адаптеры
 ========
 
 * [Fenom + Yii](https://bitbucket.org/RSol/rfenomviewrender)
 * [Fenom + Kohana](https://github.com/2bj/kofenom) — Kofenom
 * Fenom + Symphony
 * Fenom + Symphony2
-* Fenom + Zend Framework
+* Fenom + Zend Framework 2

docs/ru/configuration.md

@@ -1,52 +1,55 @@
-Setup
+Настройка
-=====
+=========
 
 ## Configure
 
-### Template cache
+### Кеш шаблонов
 
 ```php
 $fenom->setCompileDir($dir);
 ```
 
-This method set the name of the directory where template caches are stored. By default this is `/tmp`. This directory must be writeable.
+Задает имя каталога, в котором хранятся компилированные шаблоны. По умолчанию это `/tmp`. Каталог дожен быть доступен на запись.
 
-### Template settings
+### Параметры обработчика
 
+Установка параметров через фабрику
 ```php
-// set options using factory
 $fenom = Fenom::factory($tpl_dir, $compile_dir, $options);
-// or inline using method setOptions
-$fenom->setOptions($options);
 ```
 
-Options may by associative array like `'option_name' => true` or bitwise mask.
+Установка параметров через метод
+```php
+$fenom->setOptions($options);
+```
+В обоих случаях аргумет `$options` может быть массивом или битовой маской.
+В массиве ключем должно быть название параметра, а ключем — булевый флаг `true` (активировать) или `false` (деактивировать).
+Битавая маска должна состоять из занчений констант из таблице ниже
 
-| Option name            | Constant                  | Description  | Affect  |
+| Название параметра     | Константа                 | Описание  | Эффект  |
 | ---------------------- | ------------------------- | ------------ | ------- |
-| *disable_methods*      | `Fenom::DENY_METHODS`     | disable calling methods of objects in templates.  | |
+| *disable_methods*      | `Fenom::DENY_METHODS`     | отключает воззможность вызова методов в шаблоне  | |
-| *disable_native_funcs* | `Fenom::DENY_NATIVE_FUNCS`| disable calling native function in templates, except allowed. | |
+| *disable_native_funcs* | `Fenom::DENY_NATIVE_FUNCS`| отключает возможность использования фунций PHP, за исключением разрешенных  | |
-| *auto_reload*          | `Fenom::AUTO_RELOAD`      | reload template if source will be changed | decreases performance |
+| *auto_reload*          | `Fenom::AUTO_RELOAD`      | автоматически пересобирать кеш шаблона если шаблон изменился | понижает производительность |
-| *force_compile*        | `Fenom::FORCE_COMPILE`    | recompile template every time when the template renders | very decreases performance |
+| *force_compile*        | `Fenom::FORCE_COMPILE`    | каждый раз пересобирать кеш шаблонов (рекоммендуется только для отладки)| очень сильно понижает производительность |
-| *disable_cache*        | `Fenom::DISABLE_CACHE`    | disable compile cache | greatly decreases performance |
+| *disable_cache*        | `Fenom::DISABLE_CACHE`    | не кешировать компилированный шаблон | эпично понижает производительность |
-| *force_include*        | `Fenom::FORCE_INCLUDE`    | paste template body instead of include-tag | increases performance, increases cache size |
+| *force_include*        | `Fenom::FORCE_INCLUDE`    | стараться по возможности вставить код дочернего шаблона в родительский при подключении шаблона  | повышает производительность, увеличивает размер файлов в кеше, уменьшает количество файлов в кеше |
-| *auto_escape*          | `Fenom::AUTO_ESCAPE`      | html-escape each variables outputs | decreases performance |
+| *auto_escape*          | `Fenom::AUTO_ESCAPE`      | автоматически экранировать HTML сущности при выводе переменных в шаблон | понижает производительность |
-| *force_verify*         | `Fenom::FORCE_VERIFY`     | check existence every used variable | decreases performance |
+| *force_verify*         | `Fenom::FORCE_VERIFY`     | автоматически проверять существование переменной перед использованием в шаблоне | понижает производительность |
-<!-- | *auto_trim*            | `Fenom::AUTO_TRIM`        | remove space-characters before and after tags | | -->
+| *disable_statics*      | `Fenom::DENY_STATICS`     | отключает воззможность вызова статических методов в шаблоне | |
-| *disable_statics*      | `Fenom::DENY_STATICS`     | disable calling static methods in templates. | |
+| *strip*                | `Fenom::AUTO_STRIP`       | удаляет лишиние пробелы в шаблоне | уменьшает размер кеша |
-| *strip*                | `Fenom::AUTO_STRIP`            | strip all whitespaces in templates. | decrease cache size |
 
 ```php
 $fenom->setOptions(array(
     "compile_check" => true,
     "force_include" => true
 ));
-// same
+// тоже самое что и
 $fenom->setOptions(Fenom::AUTO_RELOAD | Fenom::FORCE_INCLUDE);
 ```
 
-**Note**
+**Замечание**
-By default all options disabled
+По умолчанию все параметры деактивированы.
 
 ## Extends
 

docs/ru/helpme.md

@@ -1,9 +0,0 @@
-Требуется помощь в переводе документации
-========================================
-
-Принимаю любую помощь в переводе статей документации. Вносить правки в документацию можете любым удобным способом:
-
-* Сделать merge request (нажав `Edit` вверху файла)
-* Прислать адрес статьи и что на что заменить. В письме лучше укажите `Fenom docs`.
-
-Заранее благодарен!

docs/ru/operators.md

@@ -1,55 +1,63 @@
-Operators
+Операторы
 =========
 
-### Arithmetic operators
+### Арифметические операторы
 
-* `$a + $b` - addition
+Все же помнят арифметику?
-* `$a - $b` - subtraction
+
-* `$a * $b` - multiplication
+* `-$a`     - отрицание знака, смена знака `$a`.
-* `$a / $b` - division
+* `$a + $b` - сложение, сумма `$a` и `$b`.
-* `$a % $b` - modulus
+* `$a - $b` - вычитаение, разность `$a` и `$b`.
+* `$a * $b` - умножение, произведение `$a` и `$b`.
+* `$a / $b` - деление, частное от деления `$a` на `$b`.
+* `$a % $b` - деление по модулю, целочисленный остаток от деления `$a` на `$b`.
 
 ```smarty
 {$a + $b * $c/$d - $e*5 + 1e3}
 ```
 
-### Logical operators
+### Логические операторы
 
-* `$a || $b` - or
+* `$a || $b` - логичесое ИЛИ
-* `$a && $b` - and
+* `$a && $b` - лигическое И
-* `!$a` - not, unary operator
+* `!$a` - отрицание, унарный оператор
-* `$a and $b` - and
+* `$a or $b` - логическое ИЛИ
-* `$a or $b` - or
+* `$a and $b` - логическое И
-* `$a xor $b` - xor
+* `$a xor $b` - xor, логическое сложение
 
 ```smarty
 {if $b && $c} ... {/if}
 ```
 
-### Comparison operators
+### Операторы сравнения
 
-* `$a < $b` - less than
+* `$a < $b` - строгое неравество, `$a` меньше `$b`
-* `$a > $b` - greater than
+* `$a > $b` - строгое неравество, `$a` больше `$b`
-* `$a <= $b` - less than or equal to
+* `$a <= $b` - не строгое не равество, `$a` меньше или равно `$b`
-* `$a >= $b` - greater than or equal to
+* `$a >= $b` - не строгое не равество, `$a` больше или равно `$b`
-* `$a == $b` - equal
+* `$a == $b` - Равно, `$a` равно `$b`
-* `$a === $b` - identical
+* `$a === $b` - Тождественно равно, `$a` иденично `$b`. Отличается от равества тем что проверяет так же тип значений; если '0' == 0 — истина, то уже '0' === 0 — ложно.
-* `$a !== $b` - not identical
+* `$a !== $b` - не иденично, `$a` отличается от `$b`
-* `$a != $b` - not equal
+* `$a != $b` - неравенство, `$a` отличается от `$b`
-* `$a <> $b` - not equal
+* `$a <> $b` - неравенство
 
 ```smarty
 {if $b >= 5} ... {/if}
 ```
 
-### Bitwise operators
+В случае, если вы сравниваете число со строкой или две строки, содержащие числа, каждая строка будет преобразована в число, и сравниваться они будут как числа.
+Преобразование типов не происходит при использовании `===` или `!==` так как в этом случае кроме самих значений сравниваются еще и типы.
 
-* `$a | $b` - or
+### Побитовые операторы
-* `$a & $b` - and
+
-* `$a ^ $b` - xor
+Побитовые операторы позволяют считывать и устанавливать конкретные биты целых чисел.
-* `~$a` - not, unary operator
+
-* `$a << $b` - shift left
+* `$a | $b` - битовое ИЛИ, устанавливаются те биты, которые установлены в `$a` или в `$b`.
-* `$a >> $b` - shift right
+* `$a & $b` - битовое И, устанавливаются только те биты, которые установлены и в `$a`, и в `$b`.
+* `$a ^ $b` - битовое исключающее ИЛИ, устанавливаются только те биты, которые установлены либо только в `$a`, либо только в `$b`, но не в обоих одновременно.
+* `~$a` - битовое отрицание, устанавливаются те биты, которые не установлены в `$a`, и наоборот.
+* `$a << $b` - битовый сдвиг влево, все биты переменной `$a` сдвигаются на `$b` позиций влево (каждая позиция подразумевает "умножение на 2")
+* `$a >> $b` - битовый сдвиг вправо, все биты переменной `$a` сдвигаются на `$b` позиций вправо (каждая позиция подразумевает "деление на 2")
 
 ```smarty
 {if $a & 1} {var $b = 4 | $flags} {/if}

docs/ru/readme.md

@@ -21,7 +21,7 @@ Documentation
 * [if](./tags/if.md), `elseif` и `else` — условный оператор
 * [foreach](./tags/foreach.md), `foreaelse`, `break` and `continue` — перебор элементов массива или объекта
 * [for](./tags/for.md), `forelse`, `break` and `continue` — цикл
-* [switch](./tags/switch.md), `case`, `default` —
+* [switch](./tags/switch.md), `case`, `default` — груповой условный оператор
 * [cycle](./tags/cycle.md) — циклицеский перебор массива значений
 * [include](./tags/include.md), `insert` — вставляет и испольняет указанный шаблон
 * [extends](./tags/extends.md), `use`, `block` и `parent` — наследование шаблонов

docs/ru/syntax.md

@@ -205,7 +205,7 @@ but if use single quote any template expressions will be on display as it is
 {var $c = 7E-10}
 ```
 
-### Операции над переменными
+### Операции
 
 Как и любой другой язык программирования/шаблонизации Fenom поддерживает множество различных операторов: