translit3.txt     Дополнение, используемое для транслитерации текста
=============================================================================
CONTENTS                                                       tr3-contents
    1. Введение                                        tr3-intro
    2. Предоставляемая функциональность                tr3-functionality
        2.1. Команды                                   tr3-commands
        2.2. Функции                                   tr3-functions
        2.3. Привязки                                  tr3-mappings
    3. Настройки                                       tr3-options
    4. Обычная транслитерация                          tr3-trs
        4.1. Плагины для обычной транслитерации        tr3-trs-plugins
    5. Транслитерация по мере ввода                    tr3-tof
        5.1. Плагины для транслитерации по мере ввода  tr3-tof-plugins
    6. Таблица транслитерации                          tr3-transsymb
        6.1. Получение таблицы транслитерации          tr3-transsymb-arg
        6.2. Внутренний формат таблицы транслитерации  tr3-transsymb-int
        6.3. Таблица транслитерации по умолчанию       tr3-transsymb-def
=============================================================================
1. Введение                                                       tr3-intro
Данное дополнение предоставляет пользователю возможность преобразовывать одну 
последовательность символов в другую. Типичным примером является 
транслитерация символов латинского алфавита в символы русского алфавита, 
нужная для ввода русских символов в системах без русской раскладки (или, как 
автору, для того, чтобы не учить слепой ввод для двух раскладок).
Возможности дополнения:
    — транслитерация текста с помощью функции, транслитерация выделения
      и диапозона линий, транслитерация по мере ввода;
    — установка режима транслитерации по мере ввода в конкретном буфере или
      во всех открытых буферах и при открытии нового буфера;
    — возможность написания плагинов, позволяющих изменить вывод
      транслитерирующей функции;
    — возможность написания плагинов, вмешивающихся в процесс транслитерации
      по мере ввода;
    — получение таблицы транслитерации из файла, переменной, словаря
      и результата выполнения функции;
    — вывод таблицы транслитерации на экран.
Для работы необходимы дополнения chk, json, stuf и load.
=============================================================================
2. Предоставляемая функциональность                       tr3-functionality
Данным дополнением предоставляется одна команда и набор функций, причём как 
команда, так и все функции в зависимости от настроек могут иметь приставки, 
отличные от приставки по умолчанию Tr3 (см. load-opt-_fprefix 
и load-opt-_cprefix). Внутри дополнения не используются ни команды, ни 
внешние функции данного или какого-либо другого дополнения, поэтому вы можете 
менять эти приставки. Возможные значения аргумента {transsymb} можно 
посмотреть в разделе tr3-transsymb-argNote в командной строке вы можете 
использовать только строковые значения.
-----------------------------------------------------------------------------
2.1. Команды                                                   tr3-commands
                                                                tr3-actions
:Tr3Command[!] {action} …                        tr3-:Command :Tr3Command
                Единственная команда, предоставляемая данным дополнением. При 
                наличии переменной g:tr3Options, содержащей ключ _cprefix 
                (см. load-opt-_cprefix), может начинаться не с Tr3, а со 
                значения этого ключа. Некоторые действия принимают 
                необязательный аргумент {transsymb}. Его значение надо 
                смотреть в разделе tr3-transsymb-arg.
                Действия данной команды в зависимости от {action}:
                                                   tr3-action-transliterate
:[range]Tr3Command transliterate {target} [using {transsymb}]
                В зависимости от {target}, транслитерировать либо выделение 
                ({target}==selection), либо диапозон линий ({target}==lines). 
                Если диапозон не указан, то транслитерировать строку под 
                курсором. Транслитерировать выделенный блок не рекомендуется, 
                если настроен автоматический перенос строк.
:Tr3Command[!] tof start [{transsymb}]                 tr3-action-tof-start
                Установить режим транслитерации по мере ввода для текущего 
                буфера (вариант с восклицательным знаком — для всех буферов).
:Tr3Command[!] tof stop                                 tr3-action-tof-stop
                Отменить режим транслитерации по мере ввода для текущего 
                буфера (вариант с восклицательным знаком — для всех буферов).
:Tr3Command tof restart                              tr3-action-tof-restart
                Отменить режим транслитерации по мере ввода для текущего 
                буфера и установить его заново.
                                                           tr3-action-print
:Tr3Command print [transsymb {transsymb}] [columns {columns}]
                Отобразить таблицу транслитерации на экране в {columns} 
                колонок (по умолчанию: -2, что значит: по ширине экрана).
:Tr3Command[!] add {srcstr} {trstr} [to {transsymb}]         tr3-action-add
                Добавить транслитерируемую последовательность {srcstr}
                которая будет транслитерироваться как {trstr} и сохранить 
                таблицу транслитерации (см. tr3-action-save). Версия 
                с восклицательным знаком допускает перезапись существующей 
                последовательности.
:Tr3Command[!] del[ete] {srcstr} [from {transsymb}]          tr3-action-del
                Удалить последовательность {srcstr} и сохранить таблицу 
                транслитерации (см. tr3-action-save). Версия 
                с восклицательным знаком удаляет все последовательности, 
                начинающиеся с данной.
                                                       tr3-action-setoption
:Tr3Command[!] setoption {option} {value} for {srcstr} [in {transsymb}]
                Установить настройку {option} в значение {value} для 
                последовательности {srcstr} и сохранить таблицу транслитерации 
                (см. tr3-action-save). Для получения списка настроек и их 
                значений см. tr3-transsymb-options. Версия с восклицательным 
                знаком перезаписывает существующую настройку.
                                                       tr3-action-deloption
:Tr3Command deloption {option} for {srcstr} [in {transsymb}]
                Удалить настройку {option} для последовательности {srcstr} 
                и сохранить таблицу транслитерации (см. tr3-action-save). 
                Для получения списка настроек см. tr3-transsymb-options.
:Tr3Command save [{transsymb}]                              tr3-action-save
                Сохранить таблицу транслитерации. В зависимости от источника 
                таблицы транслитерации (см. tr3-transsymb-arg) может быть 
                сделано следующее:
                Источник    Действие
                Файл        Запись таблицы в файл в формате JSON.
                            См. json-function-dump.
                Переменная  Приравнивание переменной к таблице
                            транслитерации.
                Функция     Вызов функции с единственным аргументом —
                            изменённым словарём. Вызов производится через 
                            call(); на случай, если функция окажется 
                            словарной, в качестве третьего аргумента call 
                            указывается пустой словарь.
                Словарь     Отсутствует.
:Tr3Command cache purge {target}                     tr3-action-cache-purge
                Удалить кэш {target}:
                Значение {target}  Удаляемый кэш
                trans              Все преобразования таблиц транслитерации.
                printtrans         Преобразования таблиц транслитерации для
                                   печати.
                toftrans           Преобразования таблиц транслитерации для
                                   транслитерации по мере ввода.
:Tr3Command cache show                                tr3-action-cache-show
                Вывести на экран содержимое кэша.
-----------------------------------------------------------------------------
2.2. Функции                                                  tr3-functions
Приставка (по умолчанию — Tr3) к описываемым ниже функциям берётся из 
настройки _fprefix (см. load-opt-_fprefix). Возможные значения аргумента 
{transsymb} можно посмотреть в разделе tr3-transsymb-arg. Все аргументы, имя 
которых заканчивается на str, должны иметь строковый тип. Аргументы {replace} 
и {recurse} должны быть равны либо единице, либо нулю.
                                                 tr3-function-transliterate
Tr3transliterate({str}[, {transsymb}])                   Tr3transliterate()
                Транслитерировать строку {str}.
                                                           tr3-function-add
Tr3add({srcstr}{trstr}[, {replace}[, {transsymb}]])             Tr3add()
                Добавить транслитерируемую последовательность {srcstr}
                которая будет транслитерироваться как {trstr} и сохранить 
                таблицу транслитерации (см. tr3-action-save). Если {replace} 
                равен единице, то допускается перезаписывание существующей 
                последовательности.
                                                           tr3-function-del
Tr3del({srcstr}[, {recurse}[, {transsymb}]])                      Tr3del()
                Удалить последовательность {srcstr} и сохранить таблицу 
                транслитерации (см. tr3-action-save). Если {recurse} равен 
                единице, то удалить все последовательности, начинающиеся 
                с данной.
                                                     tr3-function-setoption
                                                             Tr3setoption()
Tr3setoption({optstr}{valuestr}{srcstr}[, {replace}[, {transsymb}]])
                Установить настройку {optstr} в значение {valuestr} для 
                последовательности {srcstr} и сохранить таблицу транслитерации 
                (см. tr3-action-save). Для получения списка настроек и их 
                значений см. tr3-transsymb-options. Если {replace} равен 
                единице, то допускается перезапись существующей настройки.
                                                     tr3-function-deloption
Tr3deloption({optstr}{srcstr}[, {transsymb}])              Tr3deloption()
                Удалить настройку {optstr} для последовательности {srcstr} 
                и сохранить таблицу транслитерации (см. tr3-action-save). 
                Для получения списка настроек см. tr3-transsymb-options.
                                                         tr3-function-print
Tr3print({columns}[, {transsymb}])                               Tr3print()
                В зависимости от значения {columns} возвращает:
                Значение {columns}  Возвращаемое значение
                        -1          Список списков из трёх элементов:
                                     — транслитерируемая последовательность
                                     — результат транслитерации
                                     — флаги
                                    Является значением по умолчанию
                         0          Список, содержащий строки, содержащие то 
                                    же, что и в предыдущем случае, но 
                                    в колонках
                        -2          Строка, содержащая таблицу
                                    транслитерации, оформленную для печати на 
                                    экран в максимально возможное количество 
                                    колонок.
                        >0          Строка, содержащая таблицу
                                    транслитерации, оформленную для печати 
                                    в {columns} колонок.
                Флаги (третья колонка):
                Флаг  Значение
                 c    Для данной последовательности действует настройка
                      «capital», равная «none». См. tr3-transsymb-options.
                 f    Для данной последовательности действует настройка
                      «capital», равная «first». См. tr3-transsymb-options.
                 d    Первым символом результирующей последовательности
                      является combining diacritics, поэтому перед первым 
                      символом для улучшения читаемости поставлена латинская 
                      буква «a».
-----------------------------------------------------------------------------
2.3. Привязки                                                 tr3-mappings
                                               tr3-<_leader> tr3-_leader
                                     tr3-option-_leader tr3-option-_maps
Данное дополнение предоставляет следующие привязки (для того, чтобы изменить 
клавиши или <_leader> (по умолчанию: «\t»), см. load-opt-_maps 
и load-opt-_leader соответственно):
Имя привязки    Клавиши по умолчанию и описание
CmdTransliterate                              tr3-mapping-CmdTransliterate
                По умолчанию: <_leader>. Показывает приглашение ко вводу, 
                транслитерирует введённую пользователем строку и вставляет 
                результат транслитерации. В отличие от 
                tr3-mapping-Transliterate, определяет привязку для командной 
                строки.
Transliterate                                    tr3-mapping-Transliterate
                По умолчанию: <_leader>. Показывает приглашение ко вводу, 
                транслитерирует введённую пользователем строку и вставляет 
                результат транслитерации. Эта привязка, так же как и все 
                последующие, определяется для режима ввода.
TransliterateWord                            tr3-mapping-TransliterateWord
                По умолчанию: <_leader>w. Транслитерирует слово под 
                курсором.
TransliterateWORD                            tr3-mapping-TransliterateWORD
                По умолчанию: <_leader>W. Транслитерирует СЛОВО под курсором.
StartToF                                              tr3-mapping-StartToF
                По умолчанию: <_leader>s. Включает режим транслитерации по 
                мере ввода.
StopToF                                                tr3-mapping-StopToF
                По умолчанию: <_leader>S. Отключает режим транслитерации по 
                мере ввода.
TranslitReplace                                tr3-mapping-TranslitReplace
                По умолчанию: <_leader>r. Делает то же, что и команда r, но 
                перед этим транслитерирует аргумент (то есть, если набрать 
                «\tr<=>» достаточно быстро, то символ под курсором будет 
                заменён на «⇔»). Note привязка использует значение 
                'timeoutlen' если включена настройка 'timeout'Note привязка 
                работает корректно только если результат транслитерации имеет 
                длину, равную одному символу.
                Все следующие привязки работают аналогично TranslitReplace:
TranslitNext                                       tr3-mapping-TranslitNext
TranslitPrev                                       tr3-mapping-TranslitPrev
TranslitToNext                                   tr3-mapping-TranslitToNext
TranslitToPrev                                   tr3-mapping-TranslitToPrev
                По умолчанию: <_leader>f, <_leader>F, <_leader>t, <_leader>T. 
                Являются заменой командам fFt и T соответственно.
=============================================================================
3. Настройки                                                    tr3-options
                                                b:tr3Options g:tr3Options
Данное дополнение берёт настройки из словаря с именем tr3Options. Никакие 
другие внешние переменные не проверяются, если этого не требуют настройки. За 
несколькими исключениями, настойки грузятся следующим образом: сначала 
проверяется словарь b:tr3Options, затем словарь g:tr3Options и, если настройка 
так и не была найдена, внутренний словарь, содержащий настройки по умолчанию. 
В случае, если настройка была найдена, то она проверяется на правильность. При 
нахождении ошибки выбрасывается исключение. Список настроек:
Настройка     Значение
                                                          tr3-option-BrkSeq
BrkSeq        Строка; последовательность, прерывающая транслитерацию.
              Используется плагинами tr3-trs-plug-brk и tr3-tof-plug-brk.
              Значение по умолчанию: '@'.
                                                          tr3-option-EscSeq
EscSeq        Строка; последовательность, экранирующая следующий символ.
              Используется плагинами tr3-trs-plug-esc 
              и tr3-trs-plug-notrans.
              Значение по умолчанию: '\'.
                                                     tr3-option-StopTrSymbs
StopTrSymbs   Словарь, каждому ключу которого соответствует строковое
              значение; ключами служат последовательности, прерывающие 
              транслитерацию, при этом последовательность заменяется на 
              соответствующее значение из данного словаря.
              Используется плагинами tr3-trs-plug-notrans 
              и tr3-tof-plug-notrans.
              Значение по умолчанию: {'%': ''}
                                                    tr3-option-StartTrSymbs
StartTrSymbs  Словарь, каждому ключу которого соответствует строковое
              значение; ключами служат последовательности, восстанавливающие 
              прерванную транслитерацию (см. tr3-option-StopTrSymbs), при 
              этом последовательность заменяется на соответствующее значение 
              из данного словаря.
              Используется плагинами tr3-trs-plug-notrans 
              и tr3-tof-plug-notrans.
              Значение по умолчанию: {'%': ''}
                                                     tr3-option-NoTransWord
NoTransWord   Словарь, каждому ключу которого соответствует строковое
              значение; ключами служат последовательности, экранирующие всё 
              слово до пробельного символа, при этом последовательность 
              заменяется на соответствующее значение из данного словаря.
              Используется плагином tr3-trs-plug-notransword.
              Значение по умолчанию: {'%%': ''}
DefaultTranssymb                                tr3-option-DefaultTranssymb
              Таблица транслитерации по умолчанию. См. tr3-transsymb-arg.
              Значение по умолчанию: transsymb
ConfigDir                                              tr3-option-ConfigDir
              Место, где храняться основные таблицы транслитерации. 
              См. tr3-transsymb-arg. Значение по умолчанию:
                                   {plugin-install-dir}/config/translit3
                                                           tr3-option-Plugs
Plugs         Плагины для обычной транслитерации. См. tr3-trs-option-Plugs.
              Значение по умолчанию: {"Before": ["brk"],
                                       "After": ["esc", "notransword",
                                                 "notrans"]}
                                                        tr3-option-ToFPlugs
ToFPlugs      Плагины для транслитерации по мере ввода.
              См. tr3-tof-option-ToFPlugs.
              Значение по умолчанию: ["notrans", "brk"]
                                                       tr3-option-WriteFunc
WriteFunc     Имя функции, которая будет использована для записи символов 
              в буфер в режиме транслитерации по мере ввода. Если данная 
              настройка равна нулю или отстутствует, то tr3-action-tof-start 
              определяет <expr> привязки: >
                  inoremap <expr> <buffer> {c} {str}
<             где {c} — символ, который можно транслитерировать, а {str} — 
              выражение, которое возвращает результат транслитерации. Если 
              данная настройка равна имени функции, то tr3-action-tof-start 
              создаст привязки совсем другого вида: >
                  inoremap <buffer> {c} <C-\><C-o>:call call({WF}, [{str}], {})
<             где {WF} — имя функции, которая будет использована для записи 
              символов в буфер. Вместо своей функции можно использовать одну 
              из предопределённых функция, а именно:
              WriteFunc   Описание
              @conque     Функция добавляет поддержку дополнения Conque Shell.
                                                       tr3-option-DoNotLoad
DoNotLoad     Если данный ключ присутствует в словаре g:tr3Options до начала
              загрузки дополнения, то дополнение не загружается. Не 
              предотвращает загрузку дополнения, если первая стадия загрузки 
              уже прошла.
              Значение по умолчанию отсутствует.
=============================================================================
4. Обычная транслитерация                                           tr3-trs
Под обычной транслитерацией понимается транслитерация с помощью функции 
Tr3transliterate() или действия tr3-action-transliterate команды 
:Tr3Command.
-----------------------------------------------------------------------------
4.1. Плагины для обычной транслитерации                     tr3-trs-plugins
Обычная транслитерация происходит следующим образом:
1. Проверяется, не начинается ли текущая строка с регулярного выражения, 
   активирующего какой-либо плагин из настройки Plug.Before. Если да, то 
   запускается соответствующий плагин. В зависимости от возвращённого плагином 
   статуса на этом транслитерация может быть прервана.
2. Проверяется, находится ли текущий символ в текущей таблице транслитерации. 
   Если да, то функция транслитерации запускается рекурсивно для данной строки 
   без первого символа. Если функция транслитерации закончила успешно, то 
   транслитерация прерывается.
3. Проверяется, есть ли ключ «none» в текущей таблице транслитерации. Если он 
   есть, то транслитерация прерывается.
4. Если это первый запуск функции (в данный момент не транслитерируется 
   никакой последовательности), то также проверяется, не начинается ли текущая 
   строка с регулярного выражения, активирующего какой-либо плагин из 
   настройки Plug.After. Если да, то запускается соответствующий плагин. 
   В зависимости от возвращённого плагином статуса на этом транслитерация 
   может быть прервана.
5. Функция транслитерации повторно запускается для нетранслитерированной части 
   исходной строки.
4.1.1. Формат настроек                                 tr3-trs-option-Plugs
Каждому ключу (допустимы только два: Before и After) в настройке Plugs 
соответствует список, содержащий либо строку с именем предоставляемого данным 
дополнением плагина (см. tr3-trs-builtin-plugins), либо список с двумя 
значениями: ссылкой на функцию и строкой с регулярным выражением, которому 
должно соответствовать начало строки, чтобы плагин был запущен.
4.1.2. Требования к функции                               tr3-trs-plug-func
Функция должна принимать 5 аргументов:
Аргумент     Значение
{match}      Часть строки, совпавшая с регулярным выражением.
{tail}       Часть строки после {match}.
{transsymb}  Таблица транслитерации во внутреннем формате
             (см. tr3-transsymb-int).
{cache}      Словарь со следующими ключами:
             1. BrkSeq, EscSeq, StopTrSymbs, StartTrSymbs — словари с двумя 
                ключами: value и regex, первому ключу соответствует значение 
                соответствующей настройки, второму — регулярное выражение.
             2. Plugs — словарь с ключами Before и After, каждому из которых 
                соответствует список, содержащий списки из двух элементов.
{flags}      Флаги транслитерации: словарь с ключами upper, fstupper
             и transbeg. Значения флагов:
             Флаг      Значение
             transbeg  Допустимые значения: 1 и 0. Флаг равен единице, если
                       функция транслитерации последовательности находится на 
                       первом уровне рекурсии (транслитерирует первый символ 
                       последовательности).
             upper     Допустимые значения: 1, 0, -1, -2:
                       Значение Смысл
                           1    Результат транслитерации должен быть переведён 
                                в верхний регистр.
                           0    Первым встретившимся символом, имеющим 
                                регистр, был символ в нижнем регистре.
                          -1    Ещё не встретилось ни одного символа,
                                имеющего регистр.
                          -2    При транслитерации встретилась настройка
                                capital, равная none. 
                                См. tr3-transsymb-options.
             fstupper  Допустимые значения: 1 и 0. Значение 1 означает, что
                       при транслитерации встретилась настройка capital, равная 
                       first.
Значения словарей {transsymb}{cache} и {flags} изменять запрещено.
Функция плагина должна вернуть словарь со следующими ключами:
Ключ    Значение
status  Допустимые значения: строка, равная success, failure или pass.
        В первом и последнем случаях помимо ключа status в словаре должны 
        присутствовать все остальные ключи. Значение success означает, что 
        функция успешно отработала и не нужно запускать другие плагины или 
        пытаться что-то транслитерировать. Значение pass означает, что функция 
        успешно отработала, но тем не менее нужно продолжить проверять плагины 
        и пытаться транслитерировать дальше. Значение failure означает, что 
        результат выполнения данной функции можно проигнорировать.
delta   Допустимые значения: любое целое число, меньшее, чем длина
        {tail} и большее или равное длине {match}, взятой с противоположным 
        знаком. Успешное выполнение функции означает, что {match} и часть 
        {tail} длиною delta будут считаться транслитерированными, 
        отрицательное значение означает, что часть {match} указанной длины 
        будет считаться нетранслитерированной (Note если в качестве delta 
        будет возвращаться отрицательное значение, равное по модулю длине 
        {match}, то функция транслитерации может никогда не завершится). 
        Наличие ключа обязательно даже в случае неудачи.
result  Допустимые значения: любая строка. В случае успеха значение,
        соответствующее данному ключу будет присоединено к транслитерированной 
        строке.
flags   Флаги. Набор флагов такой же как и у аргумента {flags}. Все флаги
        обязательны.
4.1.3. Плагины, предоставляемые дополнением         tr3-trs-builtin-plugins
esc                                                        tr3-trs-plug-esc
        Экранирует следующий символ, если перед ним стоит последовательность 
        символов, указанная в настройке tr3-option-EscSeq.
        Примеры: >
           EscSeq: '\'
           «\\» → «\»
notransword                                        tr3-trs-plug-notransword
        Экранирует всё, начиная от одной из последовательностей символов, 
        являющихся ключами tr3-option-NoTransWord до следующего пробельного 
        символа. При этом последовательность символов заменяется на значение 
        по соответствующему ключу.
        Примеры: >
           NoTransWord: {"%%": "",
                         '\': '\'}
           «ab%%cde fgh» → «абcde фгх»
             «\bf tekst» → «\bf текст»
notrans                                                tr3-trs-plug-notrans
        Предотвращает транслитерацию всего, что находится между одной из 
        последовательностей символов, являющихся ключами 
        tr3-option-StopTrSymbs, и одной из последовательностей символов, 
        являющихся значениями tr3-option-StartTrSymbs. При этом 
        последовательности заменяются на значения по соответствующему ключу. 
        Внутри зоны действует экранирование с помощью tr3-option-EscSeq.
        Примеры: >
           StopTrSymbs: {'%': "",
                         '<': '<'},
           StartTrSymbs:{'%': "",
                         '>': '>'}
           EscSeq: '\'
              «ab%cde%fg» → «абcdeфг»
             «ab%cde\%fg» → «абcde%fg»
           «<i>tekst</i>» → «<i>текст</i>»
brk                                                        tr3-trs-plug-brk
        Заменяет последовательность tr3-option-BrkSeq на пустую строку. 
        Используется для безусловного разрыва последовательности 
        транслитерации.
        Примеры: >
           BrkSeq: '@'
            «sh» → «ш»
           «s@h» → «сх»
           «@@@» → «»
=============================================================================
5. Транслитерация по мере ввода                                     tr3-tof
Режим транслитерации по мере ввода устанавливается с помощью действия 
tr3-action-tof команды :Tr3Command. При этом происходит следующее:
1. Создаётся словарь, привязанный к текущему буферу через его номер.
2. Определяется список символов, входящих во все последовательности 
   транслитерации данной таблицы транслитерации.
3. К списку символов добавляются символы из настроек tr3-option-BrkSeq
   tr3-option-StopTrSymbs и tr3-option-StartTrSymbs (в последних двух 
   случаях добавляются только ключи).
4. Полученный список последовательно обходится, для каждого символа 
   добавляется привязка в режиме вставки. При этом если для данного символа 
   существует привязка, то её значение сохраняется и при отмене режима 
   транслитерации по мере ввода оно будет восстановлено (Note на данный момент 
   не существует никаких способов (кроме, возможно сохранения сессии и чтения 
   из полученного файла) узнать, какие модификаторы (<expr><script>
   <buffer> и т. д.) применялись при создании привязки, поэтому привязка 
   воссоздаётся с модификаторами <buffer> и <special>).
-----------------------------------------------------------------------------
5.1. Плагины для транслитерации по мере ввода               tr3-tof-plugins
Транслитерация по мере ввода происходит следующим образом:
1. При вводе строки из одного или нескольких символов (привязка не к одному, 
   а к нескольким символам, производится, если плагин активируется 
   последовательностью символов) вызывается функция, которой в качестве 
   аргументов передаются словарь, связанный с текущим буфером, и введённая 
   строка.
2. Проверяется, не активирован ли в данный момент какой-либо плагин. Если да, 
   то запускается он.
3. Проверяется, есть ли данная последовательность среди последовательностей, 
   вызывающих плагин. Проверка производится только если в данный момент не 
   производится транслитерация какой-либо последовательности. В случае успеха 
   проверки, вызывается соответствующий плагин.
4. Производится транслитерация. Если в данный момент транслитерируется 
   какая-либо последовательность (например, уже транслитерирован символ «s» 
   и введён символ «h»), то перед возвращением в начало результата добавляется 
   количество „<BS>“, равное количеству символов в результате предыдущей 
   транслитерации (в приведённом примере: сначала «s» транслитерируется в «с», 
   затем «h» транслитерируется в „<BS>ш”).
5.1.1. Формат настроек                              tr3-tof-option-ToFPlugs
Формат настройки ToFPlugs схож с форматом значений словаря Plugs: настройка 
ToFPlugs представляет собой список, в котором элементами являются либо 
строки-имена предоставляемых дополнением плагинов, либо список из двух 
элементов, в котором первым значением является ссылка на функцию, а вторым 
список из строк (желательно, односимвольных) либо регулярное выражение. Список 
из строк в качестве второго аргумента добавляет эти строки в список привязок, 
ввод любой строки из списка запускает плагин. Регулярное выражение ничего не 
добавляет в список привязок, плагин запускается если ввод соответствует этому 
выражению.
5.1.2. Требования к функции                               tr3-tof-plug-func
Функция плагина должна принимать два аргумента: словарь, связанный с текущим 
буфером, и строка, вызвавшая плагин.
Описание словаря:                                           tr3-tof-bufdict
Ключ словаря  Описание
transsymb     Таблица транслитерации. Изменение данного ключа нежелательно.
              См. tr3-transsymb-int.
curtrans      Список из таблиц транслитерации. При запуске плагина
              в большинстве случаев будет равным списку из одной таблицы 
              транслитерации — bufdict.transsymb.
curtrseq      Результат последней транслитерации. Используется для получения
              последовательности <BS>.
flags         Флаги. Список флагов такой же, как и в аргументе {flags}
              tr3-trs-plug-func, за исключением флага «transbeg». Его роль 
              выполняет проверка длины списка curtrans.
lastline      Номер последней линии, на которой производилась транслитерация.
              Значение может быть равно -2.
bufnr         Номер буфера, с которым связан словарь. Изменять запрещено.
exmaps        Словарь, в котором ключами служат транслитерируемые символы,
              а значениями — пара из команды для возвращения привязки и строки 
              привязки, назначенной на этот символ (см. maparg()). Изменять 
              запрещено.
vars          Переменные, используемые плагинами. Изменять чужие переменные
              запрещено. При неуспешной транслитерации очищается.
plugs         Список плагинов. Изменять запрещено.
curplugs      Список номеров текущих плагинов в bufdict.plugs. Изменение
              нежелательно.
chars         Список символов, которые вызывают функцию транслитерации.
              Изменять запрещено.
Функция плагина должна вернуть словарь с двумя ключами: status и, возможно, 
result.
Возможные значения status:
Значение  Описание
started   Означает, что плагин запущен. При этом в bufdict.curplugs
          добавляется номер плагина.
stopped   Означает, что действие плагина прекращено. Номер плагина удаляется
          из списка bufdict.curplugs.
success   Означает, что плагин отработал успешно. Попытки транслитерации
          и запуска следующих плагинов далее не продолжаются. В этом 
          и предыдущих случаях при присутствия ключа result возвращается 
          соответствующее ему значение. При отсутствие ключа result 
          возвращается пустая строка.
failure   Результат выполнения плагина игнорируется.
pass      Запуск плагинов и транслитерация далее производятся как будто
          плагин не запускался, к возвращаемому значению прибавляется 
          значение, соответствующее ключу result. Имейте ввиду, что возможен 
          повторный запуск во время транслитерации одного и того же символа, 
          если длина bufdict.curtrans больше единицы. В этом случае результат 
          первого вызова игнорируется.
5.1.3. Плагины, предоставляемые дополнением         tr3-tof-builtin-plugins
notrans                                                tr3-tof-plug-notrans
        Прерывает транслитерацию аналогично tr3-trs-plug-notrans: любая 
        строка среди ключей tr3-option-StopTrSymbs прерывает транслитерацию, 
        при этом заменяясь на соответствующее значение, а при встрече любой 
        строки из значений tr3-option-StartTrSymbs транслитерация 
        возобновляется, при этом выводится соответствующее значение.
notransword                                       tr3-tof-plug-notransword
        Прерывает транслитерацию, если был набран любой из ключей 
        tr3-option-NoTransWord. Транслитерация возобновляется при наборе 
        пробела или перевода строки.
brk                                                        tr3-tof-plug-brk
        Аналогично плагину tr3-trs-plug-brk прерывает текущую 
        последовательность, однако, в отличие от tr3-trs-plug-brk, если 
        прерывающий символ будет частью последовательности (но не будет её 
        первым символом), то он будет транслитерирован.
comm                                                     tr3-tof-plug-comm
        Присутствие этого плагина в качестве первого в списке означает, что 
        транслитерация будет происходить только внутри комментария. 
        Нахождение внутри комментария определяется по наличию в имени любой из 
        синтаксических групп, возвращаемых функцией synstack() строки 
        «comment» в любом регистре.
=============================================================================
6. Таблица транслитерации                                     tr3-transsymb
«Таблица транслитерации» представляет собой словарь. Возможные ключи:
1. Любой одиночный символ. Ему должна соответствовать либо строка-результат 
   транслитерации данного символа, либо таблица транслитерации.
2. Ключ «none». Допустим только начиная со второго уровня вложенности: 
   означает, что если следующий символ отсутствует в таблице транслитерации, 
   то результатом транслитерации будет соответствующее данному ключу значение 
   (оно должно быть строкой).
                                                      tr3-transsymb-options
3. Ключ «options». Значением данного ключа должен быть словарь, в котором есть 
   ключ «capital», которому соответствует одно из строковых значений: «none» 
   или «first». Первое строковое значение вводит запрет на транслитерацию 
   верхнего регистра. Второе значение изменяет характер создания верхнего 
   регистра: вместо того, чтобы в качестве результата транслитерации 
   возвращать результат транслитерации нижнего регистра, полностью 
   переведённый в верхний регистр, возвращается строка, в которой в верхний 
   регистр переведён только первый символ в нижнем регистре.
Пример: >
    transsymb: {'h': 'х',
               \'c': {"none": 'ц', 'h': 'ч'},
               \'x': {"none": 'ь', "options": {"capital": "none"}},
               \'|': {"options": {"capital": "first"}, 't': "\theta"}}
    «h ch Ch CH cH» → «х ч Ч Ч цХ»
              «x X» → «ь X»
            «|t |T» → «\theta \Theta»
-----------------------------------------------------------------------------
6.1. Получение таблицы транслитерации                     tr3-transsymb-arg
Аргументы функций, команд и настройка tr3-option-DefaultTranssymb позволяют 
указать таблицу транслитерации одним из следующих способов (в командах можно 
указать только строки):
1. Строка-имя переменной. Оно должно начинаться на g: или b: и букву 
   латинского алфавита и содержать только буквы латинского алфавита, цифры 
   и точку.
2. Строка-имя файла. В случае, если строка не соответствует предыдущему 
   условию, то проверяется наличие файла. Файл должен содержать таблицу 
   транслитерации в формате JSON (см. json-function-load). Имя файла в этом 
   случае либо должно начинаться с точки, либо содержать косую черту (как 
   прямую, так и обратную), либо оканчиваться на строку .json.
3. Строка-имя файла в каталоге, указанном в tr3-option-ConfigDir без 
   расширения (расширение .json подставляется автоматически). Файл должен 
   содержать таблицу транслитерации в формате JSON и иметь раширение .json. 
   Также файл не должен начинаться с точки или с буквы и двоеточия, 
   оканчиватсься на .json.json и иметь в своём имени косую черту (ни прямую, 
   ни обратную).
4. Словарь-таблица транслитерации.
5. Функция (ссылка на функцию). Функция должна поддерживать вызов без 
   аргументов для получения таблицы транслитерации и вызов с единственным 
   аргументом — изменённой таблицей транслитерации — для сохранения 
   изменений.
-----------------------------------------------------------------------------
6.2. Внутренний формат таблицы транслитерации             tr3-transsymb-int
Таблица транслитерации во внутреннем формате также представляет собой словарь. 
Возможные ключи:
1. Любой одиночный символ в нижнем регистре. Ему соответствует пара из двух 
   таблиц транслитерации: таблица транслитерации для нижнего и верхнего 
   регистров. Если таблица транслитерации для верхнего регистра отсутствует 
   (вместо неё присутствует число 1 или 2), то используется таблица 
   транслитерации для нижнего регистра. Число два соответствует настройке 
   capital, равной first. Число 0 вместо таблицы транслитерации для верхнего 
   регистра соответствует настройке capital, равной none. Также, если таблица 
   транслитерации для нижнего регистра отсутствует, то она заменяется на число 
   0.
2. Ключ «none». Соответствующее значение содержит результат транслитерации. 
   Присутствует только у вложенных таблиц транслитерации.
3. Ключ «origin». Содержит исходную таблицу транслитерации. Присутствует 
   только в корневой таблице.
4. Ключ «source». Содержит информацию об источнике, из которого получена 
   исходная таблица транслитерации. Представляет из себя пару из строки 
   и значения:
   Строка  Значение
   var     Имя переменной, из которой получена таблица транслитерации.
   file    Имя файла с исходной таблицей транслитерации.
   dict    Сама исходная таблица транслитерации.
   func    Ссылка на функцию, вернувшую исходную таблицу транслитерации.
   Присутствует только в корневой таблице. См. tr3-transsymb-arg.
-----------------------------------------------------------------------------
6.3. Таблица транслитерации по умолчанию                  tr3-transsymb-def
С дополнением поставляются две таблицы транслитерации: transsymb-ru.json 
и transsymb-ru:latex.json. Обе таблицы находятся в каталоге 
$HOME/.vim/config/translit3. Первая таблица служит для транслитерации 
latin ↔ русские символы + Unicode, вторая — latin ↔ русские символы + команды 
LaTeX.
Для использования :latex таблиц подключите пакеты textcomp, txfonts, amssymb, 
amsmath, bbm, stmaryrd, mathabx и euscript или mathrsfs. В таблицах после 
описания указаны условия использования: 
(latex[/режим][:пакет[[настройки пакета]]])
Русский алфавит:
         а (a)          a                       р (er)           r
         б (be)         b                       с (es)           s
         в (ve)         v                       т (te)           t
         г (ghe)        g                       у (u)            u
         д (de)         d                       ф (ef)           f
         е (ie)         e                       х (ha)           h
         ё (io)         ox,o',e"                ц (tse)          c
         ж (zhe)        zh                      ч (che)          ch,c',cx
         з (ze)         z                       ш (sha)          sh,w
         и (i)          i                       щ (scsha)        wh,wx,w'
         й (short i)    j,                      ъ (hard sign)    xx,x',"
         к (ka)         k                       ы (yeru)         y
         л (el)         l                       ь (soft sign)    x
         м (em)         m                       э (e)            ex,e'
         н (en)         n                       ю (yu)           ux,u'
         о (o)          o                       я (ya)           q
         п (pe)         p
Греческий алфавит:
        В таблицах для русского языка перед всеми символами следует 
        писать «|».
        α (alpha)       a               ξ (xi)          x
        β (beta)        b               ο (omicron)     o
        γ (gamma)       g               π (pi)          p
        δ (delta)       d               ρ (rho)         r
        ε (epsilon)     e               ς (final sigma) h,s'
        ζ (zeta)        z               σ (sigma)       s
        η (eta)         n,e'            τ (tau)         j,t'
        θ (theta)       t               υ (upsilon)     u
        ι (iota)        i               φ (phi)         f
        κ (kappa)       k               χ (chi)         c
        λ (lambda)      l               ψ (psi)         y,p',f'
        μ (mu)          m               ω (omega)       w
        ν (nu)          v,n'
Кавычки:
        « »     << >>   «ёлочки» (отсутствуют в :latex, так как в нём „<<“
                        и „>>“ и так заменяются на нужные кавычки)
        „ “     ,, ``   „лапки“ (отсутствуют в :latex по тем же причинам, что
                        и «ёлочки»)
        “ ”     `` ''   английские двойные кавычки (отсутствуют в :latex по
                        тем же причинам, что и «ёлочки»)
        ‘ ’     $' '    английские одиночные или марровские кавычки
                        (закрывающая кавычка отсутствует в :latex по 
                        тем же причинам, что и «ёлочки»)
        ‹ ›     $<,$>   «одиночные ёлочки»
        ‛       $'!     английская одиночная открывающая кавычка с другим
                        начертанием
        ‟       $``     английская двойная открывающая кавычка с другим
                        начертанием (обе кавычки с другим начертанием 
                        отсутствуют в :latex)
        ‚       $,      одиночная нижняя открывающая кавычка
Знаки пунктуации:
        ’       '       апостроф (отсутствует в :latex, см. выше)
        ʼ       $`      другой апостроф, в отличие от предыдущего не
                        являющийся по совместительству кавычкой (отсутствует 
                        в :latex)
        …       ...     троеточие
        –       --      короткое тирэ (en dash) (отсутствует в :latex)
        —       ---     длинное тирэ (em dash) (отсутствует в :latex: 
                        обе последовательности и так заменяются на 
                        нужные тирэ)
Другие типографские символы:
                ~       неразрывный пробел (отсутствует в :latex)
        а́       a`      ударение (здесь показано ударение на a, так как
                        ударение на пробел может привести к неожиданным 
                        результатам) (учтите, что в Unicode ударение ставится 
                        после буквы, а в LaTeX — перед буквой)
        ©       (c)     копирайт
        ®       (r)     знак зарегистрированной торговой марки
        ℗       (p)     копирайт на звукозапись (latex:textcomp)
        ™       ^tm,^t) торговая марка
        ℠       ^sm,^s) сервисная марка (latex:textcomp)
Пробелы:
        Так как в консоли пробелы невозможно различить, то сами символы не 
        приводятся.
        Пробелы отсутствуют в :latex.
        _       тонкая шпация
        _m      круглая шпация
        _d      полукруглая (половина круглой) шпация
        _t      третная (треть круглой) шпация
        _q      четвертная (четверть круглой) шпация
        _o      1/6 круглой
        _.      волосяная шпация (1/10—1/16 круглой)
Обозначения величин:
        ‰       $%      промилле
        ′       $m      угловая минута/фут (latex/math)
        ″       $s,$"   угловая секунда/дюйм (latex/math:mathabx)
        °       $0      градус
        ℃       $C      градус Цельсия (latex:textcomp)
        ℉       $F      градус Фаренгейта (latex:textcomp)
        Å       $A      Ангстрем (latex/text)
        K       $K      Кельвин (отсутствует в :latex)
        Ω       $O      Ом (latex:textcomp)
        ℔       $P      фунт
Константы:
        ℎ       $h      постоянная планка (отсутствует в :latex)
        ℏ       $h-     постоянная планка, умноженная на 2π 
                        (latex/math)
        π       |p      число пи
        ℯ       $e      экспонента (отсутствует в :latex)
Множества (latex/math:bbm):
        ℕ       $N      натуральные числа
        ℤ       $Z      целые числа
        ℚ       $Q      рациональные числа
        ℝ       $R      действительные числа
        ℂ       $c      комплексные числа
Стрелки (latex/math):
        ←,→     <-,->   стрелки
        ↢,↣     <-<,>-> стрелки с хвостиком (latex/math:amssymb)
        ↤ ↦     <-| |-> стрелка, выходящая из линии (первая стрелка требует
                        latex/math:stmaryrd)
        ↔       <->     стрелка влево-вправо
        ⇐,⇒     $<=,=>  двойная стрелка
        ⇍,⇏     /<=,/=> зачеркнутая двойная стрелка (latex/math:amssymb)
        ⇔       <=>     двойная стрелка влево-вправо
        ⇎       /<=>    зачеркнутая двойная стрелка влево-вправо
                        (latex/math:amssymb)
Логика (latex/math):
        ¬       $!      логическое НЕ
        ∧,∨     $+,$*   логические И/ИЛИ
        ⋀,⋁     $+n,$*n n-арные логические И/ИЛИ
        ⊼,⊽     $+!,$*! логичские И-НЕ (NAND)/ИЛИ-НЕ (NOR)
        ⊻       $*x     логическое исключающее ИЛИ 
                        (latex/math:amssymb)
        ∀       $a      для всех
        ∃       $ex     существует
        ∄       $/e     не существует (latex/math:amssymb)
        ∁       $co     дополнение (latex/math:amssymb)
Теория множеств (latex/math):
        ∩,∪     $u,$U   пересечение/объединение
        ⋂,⋃     $un,$Un n-арные пересечение/объединение
        ∖       $-      вычитание из множества
        ∋,∈     $<e,$>e содержит в качестве элемента/является элементом
        ∉,∌     /<e,/>e не содержит в качестве элемента/не является элементом
                        (второе требует latex/math:mathabx)
        ⊃,⊂     $<c,$>c включает в себя/включено в
        ⊄,⊅     /<c,/>c не включает в себя/не включено в
        ⊕,⊗     $+),$*) прямая сумма/тензорное произведение
        ⋀,⋁     $+n,$*n n-арные прямая сумма/тензорное произведение
        ∅       $n      пустое множество
Символы отношений (latex/math):
        ≤,≥     <=,>=   меньше/больше либо равны
        ≪,≫     $<<,$>> много меньше/больше
        ≡,≢     =-,/=-  тождественно равно/не равно
        ≠       /=      не равно
        ≈       $~      приблизительно равно
        ⊥       $|_     перпендикулярно
        ∥       $||     параллельно
        ∝       $=c     пропорционально
Другие математические операции (latex/math):
        ⊕,⊗     $+),$*) прямая сумма/тензорное произведение
        ⋀,⋁     $+n,$*n n-арные прямая сумма/тензорное произведение
        ∙,×     $.,$x   умножение
        ∕       $//     деление (отсутствует в :latex)
        ⁄       $/      дробная черта (отсутствует в :latex)
        ÷       $/-     может использоваться в качестве знака деления
        ∫,∬,∭   $i,$ii,$iii
                        одинарный/двойной/тройной интегралы (двойной и тройной 
                        интегралы требуют latex/math:amsmath)
        ∮,∯,∰   $o,$oo,$ooo
                        одинарный/двойной/тройной интегралы по замкнотуму 
                        контуру (двойной и тройной интегралы требуют 
                        latex/math:txfonts)
        ∲,∳     $oc,$occ
                        интеграл по/против часовой стрелки по замкнутуму 
                        контуру (latex/math:txfonts)
        ∑,∏     $S,$p   n-арные сумма/произведение
        √,∛,∜   $\,$\3,$\4
                        квадратный корень, кубический корень, корень четвёртой 
                        степени
        ∂       $d      частичный дифференциал
        ±,∓     +-,-+      плюс-минус/минус-плюс
        ⟨,⟩     |<, |>  Угловые скобки (обозначают усреднение)
Другие символы:
        №       #       номер
        ℰ       $E      ЭДС (электродвижущая сила) 
                        (latex/math:mathrsfs или 
                        latex/math:euscript[mathscr])
        ∞       $I      символ бесконечности (latex/math)
        ⁰-⁹     ^0-^9   верхние индексы 0-9 (отсутствуют в ru:latex)
        ₀-₉     _0-_9   нижние индексы 0—9 (отсутствуют в ru:latex)
        ∠       $/_     угол
vim: ft=help:tw=78