im.pidgin.pidgin: e1ef22c0f8bc82d7c69f7e57052e8a799a7241b7
resiak at soc.pidgin.im
resiak at soc.pidgin.im
Sun Oct 7 15:10:45 EDT 2007
revision: e1ef22c0f8bc82d7c69f7e57052e8a799a7241b7
date: 2007-10-07T19:07:06
author: resiak at soc.pidgin.im
branch: im.pidgin.pidgin
changelog:
I basically copied most of
http://developer.pidgin.im/wiki/CHowTo/ChoosingPluginIds into plugin-ids.dox.
manifest:
format_version "1"
new_manifest [9ce7422b52d102a460bebd0702bd87e8dc3d990d]
old_revision [a680cb58f48e480d6d7da05380199605c752beb1]
patch "doc/plugin-ids.dox"
from [b0de7792fca0a764858fff762f5ed37a0618a892]
to [8a91b8e86382e145a6c34347ec4a45e3024b856b]
-------------- next part --------------
============================================================
--- doc/plugin-ids.dox b0de7792fca0a764858fff762f5ed37a0618a892
+++ doc/plugin-ids.dox 8a91b8e86382e145a6c34347ec4a45e3024b856b
@@ -1,12 +1,12 @@
/** @page plugin-ids Plugin IDs
@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,28 +15,80 @@
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 that person. It
- @em should be your SourceForge ID. Do @em not leave this field
- blank.
+ 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 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.
+ 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 (-).
+
+ @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.
+
+ 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
on the Pidgin website, where users can download and install new plugins.
More information about the Commits
mailing list