annotate doc/plugin-ids.dox @ 22651:21f1acb9090f

Patch from Maiku: "When the buddy list is set to sort contacts by status, contacts who have a tune set are scored lower than contacts who aren't, even though their status apart from that is the same." Also added more detail to the comment that was intended to prevent this ever happening. Fixes #5493 -- thanks!
author Will Thompson <will.thompson@collabora.co.uk>
date Sat, 12 Apr 2008 17:55:44 +0000
parents e96daf6bc511
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
7335
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
1 /** @page plugin-ids Plugin IDs
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
2
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
3 @section Introduction
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
4 Every plugin contains a unique identifier to prevent duplicate plugin
20808
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
5 loading and conflicts. Third-party plugins (that is, plugins written by
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
6 anyone who is not a libpurple, Pidgin, or Finch developer) are expected
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
7 to use a plugin ID that follows a specific format. This format
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
8 categorizes plugins and makes duplicate IDs highly unlikely.
7335
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
9
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
10 @section Format
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
11 The basic format of a plugin ID is as follows:
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
12
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
13 <tt><i>type</i>-<i>username</i>-<i>pluginname</i></tt>
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
14
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
15 The @em type indicator specifies the type of plugin. This must be one
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
16 of the following:
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
17
20808
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
18 - core - A core libpurple plugin, capable of being loaded in any
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
19 program using libpurple. Core plugins may not contain any
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
20 UI-specific code.
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
21 - prpl - A protocol plugin. This is a special type of core plugin,
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
22 which provides libpurple the ability to connect to
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
23 another IM or chat network.
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
24 - lopl - A loader plugin, which loads scripts as plugins. Perl and
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
25 Tcl plugins are made possible by loader plugins.
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
26 - gtk - A GTK+ 2.x (a.k.a. Pidgin) plugin. These plugins may use
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
27 GTK+ code, but may not use window toolkit code, such as
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
28 X11, Win32, Cocoa, or Carbon.
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
29 - gtk-x11 - A GTK+ 2.x plugin that uses X11 code. These plugins may
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
30 use both GTK+ code and X11 code, allowing to hook into
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
31 features specific to X11.
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
32 - gtk-win32 - A GTK+ plugin that uses Win32 code. These plugins may use
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
33 both GTK+ code and Win32 code, allowing to hook into
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
34 features available on Windows.
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
35 - gnt - A GNT (a.k.a. Finch) plugin. These plugins may use GNT code.
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
36 - qpe - A plugin for the (now-abandoned) Qutopia user interface.
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
37
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
38 The @em username must be a unique identifier for you. It
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
39 @em should be your http://developer.pidgin.im Trac user ID. Failing that, you
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
40 could use your SourceForge user ID or your Freenode IRC nickname, if you
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
41 have either. The http://developer.pidgin.im Trac user ID is preferred.
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
42 Do @em not leave this field blank!
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
43
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
44 The @em pluginname is the name of your plugin. It is usually all
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
45 lowercase letters and matches the static plugin ID (the first argument to
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
46 the PURPLE_INIT_PLUGIN() macro call), although it can be anything you
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
47 like. Do @em not include version information in the plugin ID--the
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
48 #PurplePluginInfo structure already has a field for this.
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
49
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
50 @section nospaces One Last Rule for Plugin IDs
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
51
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
52 The last rule of plugin IDs is the most important of all. Plugin IDs may
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
53 @em NOT contain spaces. If you need a space, use another hyphen (-).
7335
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
54
20808
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
55 @section exceptions Exceptions to the Rule
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
56
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
57 As with any rule there are exceptions. If you browse through the source
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
58 tree you will see that the plugins we distribute with the Pidgin source
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
59 do not contain a username field. This is because while one developer may
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
60 have written each specific plugin, the plugins are maintained
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
61 collectively by the entire development team. This lack of a username
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
62 field is also an indicator that the plugin is one of our plugins and not
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
63 a third-party plugin.
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
64
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
65 Another exception to the rule is the <a
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
66 href="http://plugins.guifications.org/trac/wiki/PluginPack">Purple Plugin
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
67 Pack</a>. All plugins whose lives started in the Purple Plugin Pack use
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
68 <tt>"plugin_pack"</tt> for the username field to indicate origination in
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
69 the Purple Plugin Pack.
7335
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
70
20808
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
71 These two exceptions are mentioned here for completeness. We don't
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
72 encourage breaking the conventions set forth by the rules outlined above.
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
73
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
74 @section examples Examples of Well-Chosen Plugin IDs
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
75
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
76 The following is a list of well-chosen Plugin IDs listing a few good examples.
7335
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
77
20808
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
78 - <tt>"gtk-amc_grim-guifications"</tt> - This is the plugin ID for the
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
79 Guifications 2.x plugin.
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
80 - <tt>"gtk-rlaager-album"</tt> - This is the plugin ID for the Album
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
81 plugin, which is now part of the
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
82 Purple Plugin Pack. Its ID follows the
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
83 rules because its life started prior
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
84 to its inclusion in the Plugin Pack.
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
85 - <tt>"core-rlaager-irchelper"</tt> - This is the plugin ID for the IRC
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
86 Helper plugin, which is now part
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
87 of the Purple Plugin Pack. Its ID
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
88 follows the rules because its
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
89 life started prior to its
e96daf6bc511 I basically copied most of
Will Thompson <will.thompson@collabora.co.uk>
parents: 20807
diff changeset
90 inclusion in the Plugin Pack.
7335
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
91
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
92 @section plugin-db Plugin Database
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
93 Although it doesn't exist yet, in time there will be a plugin database
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 13863
diff changeset
94 on the Pidgin website, where users can download and install new plugins.
7335
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
95 Plugins will be accessed by your plugin ID, which is one reason why it
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
96 must be unique.
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
97
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
98 */
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
99
20807
e0613cf8c493 Add some links from signal documentation back to the documentation for the
Will Thompson <will.thompson@collabora.co.uk>
parents: 16196
diff changeset
100 // vim: syntax=c.doxygen tw=75 et