doc: plugin

docs/klish3.ru.md

@@ -1,9 +1,6 @@
 # Klish 3
 
 
-<!-- toc -->
-
-
 ## Обзор
 
 Программа klish предназначенa для организации интерфейса командной строки,
@@ -360,23 +357,79 @@ SEQ сам может быть элементом контейнера SWITCH.
 
 Обратите внимание, что даже базовый плугин с именем "klish" также не загружается
 автоматически и его надо прописывать в файлах конфигурации. В этом плугине, в
-частности, реализована навигация.
+частности, реализована навигация. Типичная конфигурация будет содержать строку:
+
+```
+<PLUGIN name="klish"/>
+```
+
+Тег `PLUGIN` не может содержать других вложенных тегов.
 
 
 #### Атрибут `name`
 
+Атрибут определяет имя, под которым плугин будет распознаваться внутри файлов
+конфигурации. Когда `ACTION` ссылается на символ, то может быть указано просто
+имя символа, а может быть уточнено, в каком плугине искать символ.
+
+```
+<ACTION sym="my_sym"\>
+
+<ACTION sym="my_sym@my_plugin"\>
+```
+
+В первом случае klish будет искать "my_sym" во всех плугинах и использует первый
+найденый. Во втором случае поиск будет производиться только в плугине
+"my_plugin". Кроме того, разные плугины могут содержать одноименные символы и
+указание плугина позволит узнать, какой из символов имелся в виду.
+
+Если не указаны атрибуты `id` и `file`, то `name` используется также для
+формирования имени файла плугина. Плугин должен иметь имя `kplugin-<name>.so` и
+находиться в директории `/usr/lib/klish/plugins` (если klish был сконфигурирован
+с `--prefix=/usr`).
+
+
 #### Атрибут `id`
 
+Атрибут используется для формирования имени файла плугина, если не указан атрибут
+`file`. Плугин должен иметь имя `kplugin-<id>.so` и находиться в директории
+`/usr/lib/klish/plugins` (если klish был сконфигурирован
+с `--prefix=/usr`).
+
+Если указан атрибут `id`, то `name` не будет использоваться для формирования
+имени файла плугина, а только для идентификации внутри файлов конфигурации.
+
+```
+<PLUGIN name="alias_for_klish" id="klish"\>
+
+<ACTION sym="nav@alias_for_klish"\>
+```
+
+
 #### Атрибут `file`
 
-#### Данные внутри тега
+Полное имя файла плугина (разделяемой библиотеки) может быть указано в явном
+виде. Если указан атрибут `file`, то никакие другие атрибуты не будут
+использоваться для формирования имени файла плугина, а будет взято значение
+`file` "как есть" и передано функции dlopen(). Это означает, что может быть
+указан как абсолютный путь, так и просто имя файла, но в таком случае файл
+должен находиться по стандартным путям, используемым при поиске разделяемой
+библиотеки.
 
+```
+<PLUGIN name="my_plugin" file="/home/ttt/my_plugin.so"\>
 
+<ACTION sym="my_sym@my_plugin"\>
 ```
-<PLUGIN name="klish"/>
 
-<PLUGIN name="script"/>
 
+#### Данные внутри тега
+
+Данные внутри тега `PLUGIN` могут быть обработаны функцией инициализации
+плугина. Формат данных остается на усмотрение самого плугина. Например,
+в качестве данных могут быть указаны настройки для плугина.
+
+```
 <PLUGIN name="sysrepo">
 	JuniperLikeShow = y
 	FirstKeyWithStatement = n