Plugin parameters...

...or "Professional ethics". Recommendations. Last revised on 30.04.2001

This document is an attempt of creating the FAR manager plugins specification (or, rather, recommendations). All materials are in plain text for now (will be divided into topics later).

This document is for programmers who write plugins for FAR manager.

You are encouraged to add, adjust, recommend, etc.

1. Plugin files MUST be packed into ZIP archive, since some servers treat RAR archives as text/plain, which results in the so-called "broken" archive.

    

2. The plugin archive MUST be supplied with a file_id.diz file, which should contain the plugin name, version, release date, short description of features (in English and Russian) and how to contact the developer. This file must be in the root of the archive.

    

3. The plugin archive should be supplied with a whatsnew.txt file (or history.txt), which should contain decription of changes (indicating version and date).

    

4. The plugin name should be the same in Plugin commands menu and in Plugins configuration menu:

   If plugin adds "Search and replace" string to the menu, then the string with the same beginning must be in the Plugins configuration menu. Strings like "This is Search and replace configuration" or "Settings" are not suitable. In this case user will find the settings for your plugin much faster.

    

5. If you supply the plugin with REG-file macros, do not forget to fill the "Description" value.

    

6. The plugin should not add multiple strings to the menu. It's better to show your own menu with all needed items instead:

   Do not add "Search", "Replace", "Search in highlighted" topics. Your plugin is just one among others, there are many other strings in the menu already. You'd better add a single "Search and replace" item, and then show a menu with "Search", "Replace" strings, etc.

    

7. The plugin MUST delete all temporary files or folders upon completion of its job.

    

8. If the plugin supports processing groups of files (using wildcards), the user should be able to specify these wildcards manually.

   Example.

   Trucer deletes trailing spaces from the file in the editor. It permits you to specify the exclusion mask. It's good. It would be bad if it didn't. Conclusion: if we don't want to handle all the files, we must provide the file mask support; and it is desirable to permit the user to adjust this setting.

    

9. If the plugin supports several actions for each of these files, you should provide the possibility to access all these actions from the commandline, user menu, and file associations.

   Example.

   "Shell link..." plugin (it's about version 1.20!) permits editing the link properties and calling the original file from the Plugins commands menu. It's bad. It would be better if Oscar (the author) added the commandline prefixes support. In that case it would be possible to make the *.LNK associations. For example, F4 - edit properties, Enter - go to the link target. This is more natural.

    

10. All messages the plugin shows on the screen (in dialogs or in menu), must be in LNG-files. Alternatively, you can use the LocMsg.cpp localization module from the Encyclopedia bonus (it is recommended to use the LocMsg.cpp in the second-level plugins or in cases when it is necessary for your plugin to respond to changes in the message file without restarting FAR. It helps you to make the plugin language-independent.

     

11. The user should have a possibility to interrupt the process during time-consuming operations. Unambiguously, the plugin MUST have this feature. Even such as Colorer. FAR should not crash because Colorer can't parse a 200KB string.

     

12. For help files, it is recommended:
    • to keep all the necessary information: "Why should I keep any readmes on my hard disk? I have them, but they're archived. Why should I search the archive when I need some additional info? IMHO, all that I need to work with plugin can be in HLF, but common information should be separated from advanced info, and links like "detailed", "advanced" should be available... So I don't have to close the plugin inappropriately and search for that separate text file. All that is "IMHO", of course."
    • At the main page
      1. show the plugin purpose and its version
      2. show links to other topics
    • It is desirable to have an "Alphabetical list" topic, where all other topics are listed.
    • There should be a link to the main page in any help topic.
    • It is necessary to check how any of the help pages appear in the 80x25 console window. Many people forget about that, and as a result only the author can see the help as he wanted it to be; others see messed-up strings. HlfViewer plugin can help in that case.

     

13. Plugin in any case should be visible while pressing F11 on any file. Also, the user shoud have a possibility to disable the OpenFilePlugin functionality in the plugin settings.

     

14. Some words about calling from commandline :-). It would be nice, if the prefix can be adjusted from the plugin configuration in order not to interfere with other plugins' prefixes.

     

15. Plugin may have no feature to change the menu items order, but if it has such feature, it should make use of Ctrl-Up/Down key combinations.

     

16. Try to use the FMENU_WRAPMODE flag while showing menus, otherwise they will be inconvenient for users.

     

17. About menus.
    1. If a menu item has an ellipsis ("...") - a dialog box should appear
    2. If a menu item has a right-aligned ">" sign - a submenu should appear
    3. In other cases, the selected command should be executed

    Example:

    Just now I wanted to print a text file, so I decided for the first time to do it from FAR using its Print Manager. I placed the cursor on the file, pressed F11 / Print Manager. In the menu I saw the "Print selected files" item, but I didn't know what would happen when I choose that item - immediate printing or some more settings invoked. The same is in the printers list. As a result it is extremely inconvenient.

     

18. If your plugin uses components (DLL, OCX, etc.), which are not a part of Windows, specify that in the "Installation" topic of your readme.txt.

    It will be perfect if you test your plugin installation on plain, "clean" Windows 95 installed using minimal configuration.

     

19. When handling keyboard events in the editor, do not forget that the cursor movement keys (Left, Right, Up, Down, PgUp, PgDn, Home, End) are not the only keys used to position the cursor - mind the Ctrl-N, Ctrl-E and Ctrl-S key combinations.

     

20. If you supplement your plugin (not being of multi-purpose type) with macros to provide the fast and convenient operation, and these macros are usable only when editing C++ sources or only with text files, you shouldn't use the ordinary macros that are kept in the Windows Registry since they affect all editors and occupy the keys at the expense of files of other types. You may offer the macros for [ESC] plugin instead (here in brackets should be the author's name, direct reference to the plugin or to the author's home page, since the plugin and URL can change) or similar plugin (there are no such plugins at the moment). They are actually the same as FAR macros, but don't have their drawbacks (they affect only user-specified file types and aren't kept in the Windows Registry).