doc

docs/klish3.ru.md

@@ -861,17 +861,17 @@ SEQ сам может быть элементом контейнера SWITCH.
 "превращается" в другие теги в зависимости от значения своих атрибутов. Следующие
 теги по внутренней реализации являются элементом `ENTRY`:
 
-* `VIEW`
-* `COMMAND`
-* `FILTER`
-* `PARAM`
-* `PTYPE`
-* `COND`
-* `HELP`
-* `COMPL`
-* `PROMPT`
-* `SWITCH`
-* `SEQ`
+* [`VIEW`](#view)
+* [`COMMAND`](#command)
+* [`FILTER`](#filter)
+* [`PARAM`](#param)
+* [`PTYPE`](#ptype)
+* [`COND`](#cond)
+* [`HELP`](#help)
+* [`COMPL`](#compl)
+* [`PROMPT`](#prompt)
+* [`SWITCH`](#switch)
+* [`SEQ`](#seq)
 
 В данном разделе будут довольно подробно рассмотрены атрибуты элемена `ENTRY`,
 зачастую являющиеся атрибутами также и других элементов. Другие элементы будут
@@ -1377,12 +1377,171 @@ SEQ сам может быть элементом контейнера SWITCH.
 
 ### COMMAND
 
+Тег `COMMAND` объявляет команду. Такая команда может быть выполнена оператором.
+Для сопоставления введенного оператором аргумента с командой используется
+атрибут [`name`](#атрибут-name). Если требуется, чтобы идентификатор команды
+внутри схемы отличался от имени команды, какой она представляется оператору,
+то `name` будет содержать внутренний идентификатор, а атрибут
+[`value`](#атрибут-value) "пользовательское" название команды. Атрибуты `name` и
+`value` могут содержать только одно слово, без пробелов.
+
+Команда мало чем отличается от элемента [`PARAM`](#param). Команда может
+содержать подкоманды. Т.е. внутри одной команды может быть объявлена другая
+команда, которая на самом деле является параметром первой команды, только этот
+параметр идентифицируется фиксированной текстовой строкой.
+
+Типичная команда содержит подсказку [`help`](#атрибут-help) или
+[`HELP`](#HELP) и, по необходимости, набор вложенных параметров
+[`PARAM`](#param). Так же в команде должны быть указаны действия
+[`ACTION`](#action), которые она выполняет.
+
+
+#### Атрибуты элемента `COMMAND`
+
+* [`name`](#атрибут-name) - идентификатор элемента.
+* [`value`](#атрибут-value) - "пользовательское" название команды.
+* [`help`](#атрибут-help) - описание элемента.
+* [`mode`](#атрибут-mode) - режим обработки вложенных элементов.
+* [`min`](#атрибуты-min-и-max) - минимальное количество аргументов командной
+строки, сопоставляемых названию команды.
+* [`max`](#атрибуты-min-и-max) - максимальное количество аргументов командной
+строки, сопоставляемых названию команды.
+* [`restore`](#атрибут-restore) - флаг восстановления "родного" для команды
+уровня в текущем пути сессии.
+* [`ref`](#атрибут-ref) - ссылка на другой `COMMAND`.
+
+
+#### Примеры
+
+```
+<PTYPE name="ptype1">
+	<ACTION sym="/INT"/>
+</PTYPE>
+
+<VIEW name="view1">
+
+	<COMMAND name="cmd1" help="First command">
+		<PARAM name="param1" ptype="/ptype1"/>
+		<ACTION sym="sym1"/>
+	</COMMAND>
+
+	<COMMAND name="cmd2">
+		<HELP>
+			<ACTION sym="script">
+			echo "Second command"
+			</ACTION>
+		</HELP>
+		<COMMAND name="cmd2_1" value="sub2" min="0" help="Subcommand">
+			<PARAM name="param1" ptype="ptype1" help="Par 1"/>
+		</COMMAND>
+		<COMMAND ref="/view1/cmd1"/>
+		<PARAM name="param2" ptype="ptype1" help="Par 2"/>
+		<ACTION sym="sym2"/>
+	</COMMAND>
+
+</VIEW>
+```
+
+Команда "cmd1" - простейший вариант команды с подсказкой, одним обязательным
+параметром типа "ptype1" и выполняемым действием.
+
+Команда "cmd2" - более сложная. Подсказка генерируется динамически. Первый
+параметр является опциональной подкомандой с "пользовательским" именем "sub2"
+и одним обязательным вложенным параметром. Т.е. оператор, желая использовать
+подкоманду должен начать свою командную строку таким образом `cmd2 sub2 ...`.
+Если опциональная подкоманда "cmd2_1" использована, то оператор должен указать
+значение её обязательного параметра. Вторая подкоманда - это ссылка на другую
+команду. Чтобы понять, что это будет значить, достаточно представить, что на
+этом месте полностью описана команда на которую указывает ссылка, т.е. "cmd1".
+За подкомандами следует обязательный числовой параметр и действие, выполняемое
+командой.
+
 
 ### FILTER
 
+Фильтр является командой [`COMMAND`](#command) с тем отличием, что команда
+фильтрации не может использоваться самостоятельно. Она лишь обрабатывает вывод
+других команд и может быть использована после основной команды и разделяющего
+символа `|`. Более подробно использование фильтров описано в разделе
+["Фильтры"](#фильтры).
+
+Для тега `FILTER` атрибут [`filter`](#атрибут-filter) принудительно выставлен в
+значение `true`. Остальные атрибуты и особенности работы совпадают с элементом
+[`COMMAND`](#command).
+
 
 ### PARAM
 
+Элемент `PARAM` описывает параметр команды. Параметр имеет тип, который задается
+либо атрибутом `ptype`, либо вложенныи элементом [`PTYPE`](#ptype). При вводе
+оператором аргумента, его значение проверяется кодом соответствующего `PTYPE` на
+корректность.
+
+В общем случае, значением для параметра может быть либо строка без пробелов,
+либо строка с пробелами, заключенная в кавычки.
+
+
+#### Атрибуты элемента `PARAM`
+
+* [`name`](#атрибут-name) - идентификатор элемента.
+* [`value`](#атрибут-value) - произвольное значение, которое может
+анализироваться кодом `PTYPE`. Для элемента `COMMAND`, который является
+частным случаем параметра, это поле используется как название "пользовательской"
+команды.
+* [`help`](#атрибут-help) - описание элемента.
+* [`mode`](#атрибут-mode) - режим обработки вложенных элементов.
+* [`min`](#атрибуты-min-и-max) - минимальное количество аргументов командной
+строки, сопоставляемых параметру.
+* [`max`](#атрибуты-min-и-max) - максимальное количество аргументов командной
+строки, сопоставляемых параметру.
+* [`order`](#атрибут-order) - режим обработки опциональных параметров.
+* [`ref`](#атрибут-ref) - ссылка на другой `COMMAND`.
+* `ptype` - ссылка на тип параметра.
+
+#### Примеры
+
+```
+<PTYPE name="ptype1">
+	<ACTION sym="/INT"/>
+</PTYPE>
+
+<VIEW name="view1">
+
+	<COMMAND name="cmd1" help="First command">
+
+		<PARAM name="param1" ptype="/ptype1" help="Param 1"/>
+
+		<PARAM name="param2" help="Param 2">
+			<PTYPE ref="/ptype1"/>
+		</PARAM>
+
+		<PARAM name="param3" help="Param 3">
+			<PTYPE>
+				<ACTION sym="/INT"/>
+			</PTYPE>
+		</PARAM>
+
+		<PARAM name="param4" ptype="/ptype1" help="Param 4">
+			<PARAM name="param5" ptype="/ptype1" help="Param 5"/>
+		</PARAM>
+
+		<ACTION sym="sym1"/>
+	</COMMAND>
+
+</VIEW>
+```
+
+Параметры "param1", "param2", "param3" - идентичны. В первом случае тип задается
+атрибутом `ptype`. Во втором - вложенным элементом `PTYPE`, который является
+ссылкой на тот же тип "ptype1". В третьем - тип параметра определяется
+"на месте", т.е. создается новый тип `PTYPE`. Но во всех трех случаях типом
+является целое число (см. атрибут `sym`). Задавать тип прямо внутри параметра
+может быть удобно, если такой тип больше нигде не нужен.
+
+Параметр "param4" имеет вложенный параметр "param5". После ввода аргумента для
+параметра "param4", оператор должен будет ввести аргумент для вложенного
+параметра.
+
 
 ### SWITCH