Merge pull request #41 from oscript-library/EvilBeaver-docs-1

Update README.md

Author: khorevaa

README.md

@@ -117,6 +117,10 @@
 $ opm install -f <ПутьКФайлу>
 ```
 
+Либо, скачать библиотеку с помощью opm:
+
+    opm install cli
+
 ## Базовые принципы
 
 При создании приложения необходимо указать имя приложения и описание:
@@ -125,35 +129,52 @@ $ opm install -f <ПутьКФайлу>
 Приложение = Новый КонсольноеПриложение("cli", "Помощник генерации приложения на основании шаблона cli");
 ```
 
-Для установки основной функции выполнения приложения необходимо создать класс, или сам модуль должен реализовать экспортную процедуру:
+Каждый возможный вариант выполнения - это "Команда". Команды могут создаваться явно, кроме того, само Приложение содержит в себе корневую (Основную) команду.
+
+Каждая команда реализуется в виде отдельного класса. Каждый такой класс обязан иметь экспортную процедуру
+
 ```bsl
 Процедура ВыполнитьКоманду(Знач Команда) Экспорт
 КонецПроцедуры
 ```
+
+Для установки основной функции выполнения приложения в приложении надо установить основное действие. В простейшем случае основным действием может выступать сам стартовый сценарий:
+
 Передать данный класс через процедуру:
 ```bsl
 Приложение.УстановитьОсновноеДействие(ЭтотОбъект)
 ```
 
+### Встроенная команда "Версия"
 
 Для добавления отображения версии через опции: ```-v, --version``` надо добавить строчку:
 
 ```bsl
 Приложение.Версия("v version", "1.2.3");
 ```
 
+Это позволит запускать приложение с ключом ``v`` или ``--version``:
+
+    my-app --version
+
+### Запуск парсера аргументов и приложения в целом
+
 Для запуска приложения необходимо добавить строчку:
 
 ```bsl
 Приложение.Запустить(АргументыКоманднойСтроки);
 ```
 
+Этот вызов является "точкой входа" в консольное приложение. В общем случае, после него уже не идет никакого дополнительного кода. Парсер анализирует аргументы и запускает команды автоматически.
+
 ## Параметры команд/приложения
 
 Все параметры разделяются на два типа:
 * Опция 
 * Аргумент
 
+В общем случае, Опции имеют имена, аргументы являются позиционными. Кроме того, по умолчанию указание опций необязательно, а аргументов - обязательно. Это можно переопределить, но дефолтное поведение именно такое. Аргумент - обязателен, опция - нет.
+
 ## Опция
 
 Опция может быть следующих простых типов:
@@ -347,7 +368,7 @@ cli поддерживает автоматическую инициализац
 
 ## Строка использования приложения (спек)
 
-Синтаксис спек базируется на POSIX.
+Синтаксис спек базируется на POSIX. Спек является грамматикой парсера аргументов и определяет порядок следования аргументов и опций в командной строке, а также вариативность параметров. Спек формируется либо вручную через указание в поле `Спек`, либо автоматически в момент вызова выполнения приложения / или команды.
 
 ### Опции
 
@@ -376,7 +397,7 @@ cli поддерживает автоматическую инициализац
 
 Пример добавления аргументов в команду:
 
-```go
+```bsl
 Команда.Аргумент("SRC", ...);
 Команда.Аргумент("DST", ...);
 ```
@@ -389,6 +410,8 @@ cli позволяет произвольно настраивать поряд
 Команда.Спек = "-f -g NAME -h PATH";
 ```
 
+В примере выше задана грамматика: в командой строке могут идти сначала опции -f и -g, затем аргумент NAME, затем опция -h, затем аргумент PATH.
+
 ## Необязательность
 
 Для того, чтобы сделать аргументы или опции необязательными, их необходимо заключить в `[...]`: