Mercurial > pidgin
annotate doc/plugin-ids.dox @ 27126:b1847ec1ba5f
These aren't needed either.
author | Mark Doliner <mark@kingant.net> |
---|---|
date | Fri, 19 Jun 2009 02:03:11 +0000 |
parents | e96daf6bc511 |
children |
rev | line source |
---|---|
7335 | 1 /** @page plugin-ids Plugin IDs |
2 | |
3 @section Introduction | |
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 | 9 |
10 @section Format | |
11 The basic format of a plugin ID is as follows: | |
12 | |
13 <tt><i>type</i>-<i>username</i>-<i>pluginname</i></tt> | |
14 | |
15 The @em type indicator specifies the type of plugin. This must be one | |
16 of the following: | |
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 | 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 | 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 | 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 | 91 |
92 @section plugin-db Plugin Database | |
93 Although it doesn't exist yet, in time there will be a plugin database | |
16196 | 94 on the Pidgin website, where users can download and install new plugins. |
7335 | 95 Plugins will be accessed by your plugin ID, which is one reason why it |
96 must be unique. | |
97 | |
98 */ | |
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 |