docs/ru/book/00_introduction.md

@@ -0,0 +1,43 @@
+# Вступление
+
+Добро пожаловать в небольшую книжку по основам языка FZLang и спасибо, что решились попробовать этот язык программирования.
+
+Для начала, стоит рассказать, что это за язык и как будет идти обучение в этой "книжке".
+
+## Что такое FZLang
+
+FZLang - это язык программирования с собственным тулчейном, включающим в себя компилятор и виртуальную машину.
+Компилятор позволяет проверить и скомпилировать исходный код программы, чтобы сохранить в переносимый файл, а виртуальная машина - выполнить программу, написанную на FZLang.
+
+Изначально, этот проект задумывался как самоучитель по компиляторостроению.
+Мне (Samsonium) было интересно разобрать:
+
+- Почему между компилятором и интерпретатором есть значимая разница?
+- Как программа, под названием "компилятор" понимает, что я хочу сделать?
+- Как устроено исполнение скомпилированной программы? Да и как, вообще, происходит процесс "перевода" с человеческого на машинный?
+
+Я занимаюсь программированием уже более 10 лет, но за всё время так и не удосужился об этом разузнать!
+
+Поэтому, этот проект был рождён как поле для экспериментов, разрабатывая который я стану лучше понимать устройство того, на чём строится весь мир программистов.
+Однако, по ходу разработки у языка стала появлятся своя форма, а также философия.
+
+Сейчас, я бы описал философию языка так: "быть удобным, как инструмент, но всегда стараться оставаться предсказуемым".
+Полагаю, любое комьюнити желает своему языку того же, но мне это помогло сделать определённый выбор в ключевых точках развития.
+
+### Как в FZLang устроена работа с памятью
+
+Изначально вопрос появился после внедрения стеков виртуальной машины, и звучал он так: "сборщик мусора или что-то другое?".
+Изучить работу сборщика было, конечно, интересно.
+Однако мне, человеку, выбравшему Java как первый язык, была знакома его "тяжесть" и "скорость" работы.
+Конечно же, отдельное "спасибо" за это можно сказать его сборщику мусора.
+
+Поэтому, вместо GC я решил посмотреть в сторону RAII и, в итоге, получил хорошую формулу гуляния объекта в программе:
+если объект подан как аргумент, то происходит "заимствование" его во вложенное окружение, и если объект возвращается, то происходит перемещение объекта в родительское окружение.
+Такой подход позволяет не делать GC, а ещё, что самое важное, получить детерминированное время жизни объекта, а значит, детерминированную память (настолько, насколько это возможно).
+
+Короче говоря, FZLang обзавёлся scope-based RAII.
+
+---
+
+Далее: [Начало работы](./01_getting-started.md)
+

docs/ru/book/01_getting-started.md

@@ -0,0 +1,47 @@
+# Начало работы
+
+Для того, чтобы начать работу с FZLang, достаточно установить себе на компьютер два исполяемых файла:
+
+- `fzc` - компилятор
+- `fz` - виртуальная машина
+
+Для того, чтобы скомпилировать программу, достаточно выполнить программу `fzc`, указав в качестве аргументов пути к файлам с исходным кодом.
+Если программа успешно скомпилировалась, то её можно запустить через программу `fz`, также указав путь скомпилированному файлу.
+Без указания компилятору пути к выходному файлу, скомпилированная программа будет сохранена как `a.fzb`.
+
+## Настройки компилятора
+
+Чтобы посмотреть о доступных настройках компилятора, выполните `fzc --help` (или `fzc -h`).
+На данный момент, справка выглядит так: 
+
+```
+Usage: fzc [flags] <sources...>
+Available flags:
+        -h      --help          Print help
+        -v      --verbose       Display compilation info (tokens, AST, consts table, etc)
+        -V      --version       Print compiler version
+        -o      --out           Set compiled file name
+```
+
+Флаг `-h` (`--help`) просто выводит ту же справку. Флаги `-v` / `--verbose` делает подробный вывод компиляции:
+
+- Какие лексемы были прочитаны;
+- Какое синтаксическое дерево было собрано;
+- Какие значения были записаны в таблицу констант;
+- Какие опкоды были записаны в программу.
+
+Флаги `-V` / `--version` выводят версию компилятора. Флаги `-o`, `--out` позволяют задать путь выходного файла.
+
+## Настройки виртуальной машины
+
+У виртуальной машины есть всего два флага: `--help` (`-h`) и `-d`.
+
+- `--help` (или `-h`) выводит справку;
+- `-d <путь к файлу>` выводит список опкодов с нумерацией. С помощью этого флага вы можете посмотреть, как вашу программу будет читать ВМ.
+
+---
+
+Далее: [Первая программа](./02_first-program.md)
+
+Назад: [Вступление](./00_introduction.md)
+