Спецификация плагинов...

...или "Правила хорошего тона". Рекомендации. Версия от 30.04.2001

Этот документ является попыткой создания спецификации (а вернее рекомендаций) на плагины к Far Manager. Пока весь материал будет идти сплошным текстом (впоследствии разгребём по разделам).

Данный документ - для программистов, пишущих плагины для Far Manager.

Добавляйте, уточняйте, рекомендуйте и...

1. Дистрибутив плагина рекомендуется упаковывать в архив ZIP (однозначно, т.к. некоторые сервера RAR-архивы "отдают" как text/plain, что в результате приводит к т.н. "битому" архиву).

    

2. Обязательно сопровождать дистрибутив файлом file_id.diz, в котором описывать название плагина, версию, дату выпуска, краткое описание для чего предназначен плагин (языки русский, английский) и координаты разработчика. Файл file_id.diz должен быть обязательно в коpне аpхива.

    

3. Также имеет смысл сопровождать дистрибутив файлом whatsnew.txt (или history.txt), в котором описывать, что было изменено (с указанием версии и даты).

    

4. Одинаковые названия для плагинов в диалогах их вызова и настройки:

   Если плагин добавляет в меню строку "поиск и замена", то и в меню "Параметры внешних модулей" должна быть добавлена строка, начинающаяся с "поиск и замена", но уж никак не "а вот это настройки для поиска и замены" или просто "настройки", тогда пользователю не придётся ломать голову над тем, как называются настройки для вашего супер-пупер плагина.

    

5. Если вы добавляете в дистрибутив плагина какие-либо макросы в виде reg-файлов, то не забывайте заполнять переменную "Description".

    

6. Стоит исключить добавление нескольких строк в меню одним плагином. Лучше плагину показывать своё меню со всеми требуемыми функциями:

   Не надо добавлять в меню строки "поиск", "замена", "поиск в выделенном", не думайте, что ваш плагин - единственный, в этом меню разных строк уже и без вас хватает, в подобном случае лучше добавьте одну строчку "поиск и замена", а при старте плагина показывайте меню со строками "поиск", "замена" и т.д.

    

7. Плагин ДОЛЖЕH чистить все временные файлы/каталоги по окончании своей работы.

    

8. Если плагин предусматривает обработку определённой группы файлов (по маске), то должна быть возможность задать эту маску, а не обрабатывать все файлы подряд.

   Пример.

   Trucer удаляет конечные пробелы из редактируемого файла. Он позволяет задать маску исключений. Это хорошо. Если бы он обрабатывал всё подряд, было б плохо. Вывод: если мы хотим обрабатывать не все файлы, то это должно быть предусмотрено путём маски исключений или включений и, желательно, настраиваемо пользователем.

    

9. Если плагин позволяет совершить несколько различных действий с такими файлами, то следует предусмотреть возможность доступа к каждому действию из командной строки/меню пользователя/ассоциаций.

   Пример.

   Плагин "shell link..." (про версию 1.20!) позволяет юзеру редактировать свойства ярлыка и переходить по нему к конкретному файлу. Это делается из меню плагинов. Это не есть хорошо. Лучше было б, если Оскар (автор) добавил работу с префиксом для командной строки. Тогда, например, можно было бы сделал ассоциацию на *.lnk по f4 - редактирование свойств, enter - переход по ссылке. Это интуитивно понятнее.

    

10. Все сообщения, выдаваемые плагином на экран (в диалогах или в меню), должны содержаться в LNG-файлах. Это позволит сделать плагин языконезависимым.

     

11. При длительных операциях дать возможность пользователю прервать процесс. То есть, примерно то, о чём говорится в статье "Обработка нажатия ESC или "Авторам долгодумающих плагинов посвящается...". Это однозначно должно быть. Даже в таких плагинах как colorer. Hельзя, чтоб Far Manager умирал из-за того что colorer не может провести парсинг строки в 200 кил.

     

12. В файлах помощи рекомендуется:
    • размещать всю необходимую для работы информацию: "зачем хранить на винте всякие ридми? Они у меня есть, но лежат в архиве. Какой смысл мне лезть в архив за доп.информацией? Imho, можно и hlf помещать всё, что нужно для работы, просто следует отделять обычные сведения от advanced и ставить ссылочки типа "подробнее", "расширенное", "advanced"... Тогда не придётся в самый неподходящий момент закрывать плагин и искать этот отдельный текстовый файл. Всё это "IMHO", естественно."
    • на главной странице
      1. указывать назначение плагина и версию
      2. ссылки на прочие разделы
    • желательно иметь раздел "Alphabetical list", где перечислены все существующие разделы.
    • в любом разделе помощи предусмотреть линки на главную страницу.
    • обязательно нужно проверить то, как будет выглядеть любая из страниц помощи при размере консоли 80x25. Многие об этом забывают, в результате, помощь показывается нормально только у авторов, а у других строчки "съезжают". Помочь в проверке может плагин HlfViewer.

     

13. Вызов плагина на текущем файле через F11 в любом случае нужно сделать из соображений хорошего тона, равно как и дать возможность пользователю отключить в настройках плагина функциональность AnalyseW.

     

14. И про вызов из командной строки через префикс не забыть бы :-). Хорошо бы, чтобы этот префикс был настраиваемым в конфигурации плагина, во избежание пересечения с чем-нибудь ещё.

     

15. Плагин в своём меню может и не иметь средств изменения порядка элементов меню, но уж если имеет, то это должно делаться по Ctrl-Up/Down.

     

16. Старайтесь всегда при показе меню использовать флаг FMENU_WRAPMODE, его отсутствие причиняет лишние неудобства пользователям.

     

17. Про меню.
    1. Если его текст заканчивается многоточием ("...") - получу диалоговое окно
    2. Если в тексте, выровненный по правому краю, имеется значок ">" - получу подменю
    3. В противном случае, будет сразу выполнена выбранная мной команда.
    Пример:

    Только что понадобилось отпечатать текст, первый раз решил сделать это из Far Manager. Через Print Manager. Ставлю курсор на файл, F11 / Print Manager. В полученном меню вижу "Print selected files" и не знаю, что будет, если я этот пункт выберу - сразу печать или что-то ещё из настроек. Аналогично дальше то же самое в списке принтеров. В итоге жутко неудобно.

     

18. Если Ваш плагин использует компоненты (DLL, OCX, etc), не входящие в состав Windows, не поленитесь указать это в разделе "Инсталляция" своего readme.txt.

    Идеально, если вы протестируете установку своего плагина на "голую" (только что установленную в минимальной конфигурации) Windows 2000.

     

19. Обрабатывая клавиатурные события редактора, не забывайте о том, что к клавишам перемещения курсора относятся не только общеупотребительные (Left, Right, Up, Down, PgUp, PgDn, Home, End), но и такие сочетания как Ctrl-N, Ctrl-E и Ctrl-S.

     

20. Если вы прилагаете к своему плагину для редактора комплект макросов для обеспечения быстрой и удобной работы, а ваш плагин не является универсальным и указанные макросы имеют смысл, например, только при редактировании исходных текстов программ на С++ или только для текстовых файлов, то не следует использовать обычные макросы, хранящиеся в реестре, т.к. они будут действовать на все редакторы и только занимать лишние клавиши в файлах другого типа. Вместо этого можно предлагать пользователю комплект макросов для плагина [ESC] (тут в скобках должно быть имя автора, прямая ссылка на плагин или просто на домашнюю страницу автора, т.к. плагин может меняться и урл будет меняться тоже) или аналогичного другого плагина (на момент написания этих строк таковой не известен), которые практически ничем не отличаются от макросов Far Manager, но лишены перечисленных недостатков (действуют только на указанные пользователем типы файлов и не занимают место в реестре).