Mercurial > pidgin
changeset 20825:de042c768169
merge of '7cc9174ede50bc7d7fdfbb47fbcdee031b053f08'
and 'e1ef22c0f8bc82d7c69f7e57052e8a799a7241b7'
| author | Will Thompson <will.thompson@collabora.co.uk> |
|---|---|
| date | Sun, 07 Oct 2007 19:07:59 +0000 |
| parents | 8e4f7b8925e7 (current diff) e96daf6bc511 (diff) |
| children | 05795b14f70b |
| files | |
| diffstat | 1 files changed, 74 insertions(+), 22 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/plugin-ids.dox Sun Oct 07 18:50:07 2007 +0000 +++ b/doc/plugin-ids.dox Sun Oct 07 19:07:59 2007 +0000 @@ -2,10 +2,10 @@ @section Introduction Every plugin contains a unique identifier to prevent duplicate plugin - loading and conflicts. This, which will be called a plugin ID from here - on, must follow a specific format. This format categorizes a plugin and - makes duplicate IDs unlikely. - + loading and conflicts. Third-party plugins (that is, plugins written by + anyone who is not a libpurple, Pidgin, or Finch developer) are expected + to use a plugin ID that follows a specific format. This format + categorizes plugins and makes duplicate IDs highly unlikely. @section Format The basic format of a plugin ID is as follows: @@ -15,27 +15,79 @@ The @em type indicator specifies the type of plugin. This must be one of the following: - - core - Core plugin, capable of being loaded in any program using - libpurple. It must not use any UI-specific code. - - prpl - Protocol plugin, providing additional protocols to - connect to. - - lopl - Loader plugin, which loads scripts as plugins (like Perl - or TCL). - - gtk - GTK+ 2.x plugin. It may use GTK+ code, but cannot use any - window toolkit code (such as X11 or Win32). - - gtk-x11 - GTK+ 2.x plugin using X11 code. - - gtk-win32 - GTK+ 2.x plugin using Win32 code. - - qpe - Gaim for Qtopia plugin. + - core - A core libpurple plugin, capable of being loaded in any + program using libpurple. Core plugins may not contain any + UI-specific code. + - prpl - A protocol plugin. This is a special type of core plugin, + which provides libpurple the ability to connect to + another IM or chat network. + - lopl - A loader plugin, which loads scripts as plugins. Perl and + Tcl plugins are made possible by loader plugins. + - gtk - A GTK+ 2.x (a.k.a. Pidgin) plugin. These plugins may use + GTK+ code, but may not use window toolkit code, such as + X11, Win32, Cocoa, or Carbon. + - gtk-x11 - A GTK+ 2.x plugin that uses X11 code. These plugins may + use both GTK+ code and X11 code, allowing to hook into + features specific to X11. + - gtk-win32 - A GTK+ plugin that uses Win32 code. These plugins may use + both GTK+ code and Win32 code, allowing to hook into + features available on Windows. + - gnt - A GNT (a.k.a. Finch) plugin. These plugins may use GNT code. + - qpe - A plugin for the (now-abandoned) Qutopia user interface. + + The @em username must be a unique identifier for you. It + @em should be your http://developer.pidgin.im Trac user ID. Failing that, you + could use your SourceForge user ID or your Freenode IRC nickname, if you + have either. The http://developer.pidgin.im Trac user ID is preferred. + Do @em not leave this field blank! + + The @em pluginname is the name of your plugin. It is usually all + lowercase letters and matches the static plugin ID (the first argument to + the PURPLE_INIT_PLUGIN() macro call), although it can be anything you + like. Do @em not include version information in the plugin ID--the + #PurplePluginInfo structure already has a field for this. + + @section nospaces One Last Rule for Plugin IDs + + The last rule of plugin IDs is the most important of all. Plugin IDs may + @em NOT contain spaces. If you need a space, use another hyphen (-). - The @em username must be a unique identifier for that person. It - @em should be your SourceForge ID. Do @em not leave this field - blank. + @section exceptions Exceptions to the Rule + + As with any rule there are exceptions. If you browse through the source + tree you will see that the plugins we distribute with the Pidgin source + do not contain a username field. This is because while one developer may + have written each specific plugin, the plugins are maintained + collectively by the entire development team. This lack of a username + field is also an indicator that the plugin is one of our plugins and not + a third-party plugin. + + Another exception to the rule is the <a + href="http://plugins.guifications.org/trac/wiki/PluginPack">Purple Plugin + Pack</a>. All plugins whose lives started in the Purple Plugin Pack use + <tt>"plugin_pack"</tt> for the username field to indicate origination in + the Purple Plugin Pack. - The @em pluginname is the name of your plugin. It can be whatever you like, - though it's common to keep it all lowercase. Do not use spaces! If you - want a space, use a '-'. Please do not put a version indicator in the ID. - The PurplePlugin structure already has a field for this. + These two exceptions are mentioned here for completeness. We don't + encourage breaking the conventions set forth by the rules outlined above. + + @section examples Examples of Well-Chosen Plugin IDs + + The following is a list of well-chosen Plugin IDs listing a few good examples. + - <tt>"gtk-amc_grim-guifications"</tt> - This is the plugin ID for the + Guifications 2.x plugin. + - <tt>"gtk-rlaager-album"</tt> - This is the plugin ID for the Album + plugin, which is now part of the + Purple Plugin Pack. Its ID follows the + rules because its life started prior + to its inclusion in the Plugin Pack. + - <tt>"core-rlaager-irchelper"</tt> - This is the plugin ID for the IRC + Helper plugin, which is now part + of the Purple Plugin Pack. Its ID + follows the rules because its + life started prior to its + inclusion in the Plugin Pack. @section plugin-db Plugin Database Although it doesn't exist yet, in time there will be a plugin database