--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/reference/libpurple/plugin-ids.dox Sun Oct 13 15:41:22 2013 +0530
@@ -0,0 +1,97 @@
+/** @page plugin-ids Plugin IDs
+
+ @section Introduction
+ Every plugin contains a unique identifier. 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:
+
+ <tt><i>type</i>-<i>username</i>-<i>pluginname</i></tt>
+
+ The @em type indicator specifies the type of plugin. This must be one
+ of the following:
+
+ - core - A core libpurple plugin, capable of being loaded in any
+ program using libpurple. Core plugins may not contain any
+ UI-specific code.
+ - protocol - A protocol plugin. This is a core plugin which provides
+ libpurple the ability to connect to another IM or chat
+ network.
+ - gtk - A GTK+ (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+ 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 https://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 https://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_PLUGIN_INIT() macro call), although it can be anything you
+ like. Do @em not include version information in the plugin ID--the
+ #PurplePluginInfo object already has a property for this.
+
+ @section nospaces One Last Rule for Plugin IDs
+
+ 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.
+ Plugins will be accessed by your plugin ID, which is one reason why it
+ must be unique.
+
+ */
+
+// vim: syntax=c.doxygen tw=75 et
