/soc/2013/ankitkv/gobjectification: b3e1dc9768b1: Updated plugin...
Ankit Vani
a at nevitus.org
Tue Oct 22 13:18:21 EDT 2013
Changeset: b3e1dc9768b1d8ea642c74c43c0af5cfb5dce652
Author: Ankit Vani <a at nevitus.org>
Date: 2013-10-22 22:14 +0530
Branch: soc.2013.gobjectification.plugins
URL: https://hg.pidgin.im/soc/2013/ankitkv/gobjectification/rev/b3e1dc9768b1
Description:
Updated plugin_ids.xml to use gtk-doc style
diffstat:
doc/reference/libpurple/plugin_ids.xml | 252 ++++++++++++++++++++++----------
1 files changed, 171 insertions(+), 81 deletions(-)
diffs (273 lines):
diff --git a/doc/reference/libpurple/plugin_ids.xml b/doc/reference/libpurple/plugin_ids.xml
--- a/doc/reference/libpurple/plugin_ids.xml
+++ b/doc/reference/libpurple/plugin_ids.xml
@@ -5,98 +5,188 @@
<chapter id="chapter-plugin-ids">
<title>Plugin IDs</title>
- <programlisting>
- @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.
+ <sect2 id="plugin-ids-introduction">
+ <title>Introduction</title>
+ <para>
+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.
+ </para>
+ </sect2>
- @section Format
- The basic format of a plugin ID is as follows:
+ <sect2 id="plugin-ids-format">
+ <title>Format</title>
+ <para>
+The basic format of a plugin ID is as follows:
- <tt><i>type</i>-<i>username</i>-<i>pluginname</i></tt>
+<programlisting>
+type-username-pluginname
+</programlisting>
+ </para>
- The @em type indicator specifies the type of plugin. This must be one
- of the following:
+ <para>
+The <emphasis>type</emphasis> 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.
+ <table>
+ <title>Types of plugins</title>
+ <tgroup cols="2">
+ <colspec colwidth="*" colnum="1" align="left"/>
+ <colspec colwidth="*" colnum="2" align="left"/>
+ <thead>
+ <row>
+<entry><emphasis>type</emphasis></entry>
+<entry>description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+<entry><literal>core</literal></entry>
+<entry>
+A core libpurple plugin, capable of being loaded in any program using libpurple.
+Core plugins may not contain any UI-specific code.
+</entry>
+ </row>
+ <row>
+<entry><literal>protocol</literal></entry>
+<entry>
+A protocol plugin. This is a core plugin which provides libpurple the ability to
+connect to another IM or chat
+network.
+</entry>
+ </row>
+ <row>
+<entry><literal>gtk</literal></entry>
+<entry>
+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.
+</entry>
+ </row>
+ <row>
+<entry><literal>gtk-x11</literal></entry>
+<entry>
+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.
+</entry>
+ </row>
+ <row>
+<entry><literal>gtk-win32</literal></entry>
+<entry>
+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.
+</entry>
+ </row>
+ <row>
+<entry><literal>gnt</literal></entry>
+<entry>
+A GNT (a.k.a. Finch) plugin. These plugins may use GNT code.
+</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
- 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!
+ <para>
+The <emphasis>username</emphasis> must be a unique identifier for you. It
+<emphasis>should</emphasis> 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 <emphasis>not</emphasis> leave this field blank!
+ </para>
- 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.
+ <para>
+The <emphasis>pluginname</emphasis> 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 <emphasis>not</emphasis> include version information in the plugin ID--the
+<literal>PurplePluginInfo</literal> object already has a property for this.
+ </para>
+ </sect2>
- @section nospaces One Last Rule for Plugin IDs
+ <sect2 id="plugin-ids-nospaces">
+ <title>One Last Rule for Plugin IDs</title>
+ <para>
+Plugin IDs may <emphasis>NOT</emphasis> contain spaces. If you need a space, use another
+hyphen (-).
+ </para>
+ </sect2>
- Plugin IDs may @em NOT contain spaces. If you need a space, use another
- hyphen (-).
+ <sect2 id="plugin-ids-exceptions">
+ <title>Exceptions to the Rule</title>
+ <para>
+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.
- @section exceptions Exceptions to the Rule
+Another exception to the rule is the <ulink
+url="http://plugins.guifications.org/trac/wiki/PluginPack">Purple Plugin
+Pack</ulink>. All plugins whose lives started in the Purple Plugin Pack use
+<literal>"plugin_pack"</literal> for the username field to indicate origination in
+the Purple Plugin Pack.
- 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.
+These two exceptions are mentioned here for completeness. We don't
+encourage breaking the conventions set forth by the rules outlined above.
+ </para>
+ </sect2>
- 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.
+ <sect2 id="plugin-ids-examples">
+ <title>Examples of Well-Chosen Plugin IDs</title>
+ <para>
+The following is a list of well-chosen Plugin IDs listing a few good examples.
- These two exceptions are mentioned here for completeness. We don't
- encourage breaking the conventions set forth by the rules outlined above.
+ <table>
+ <title>Examples</title>
+ <tgroup cols="2">
+ <colspec colwidth="*" colnum="1" align="left"/>
+ <colspec colwidth="*" colnum="2" align="left"/>
+ <thead>
+ <row>
+<entry>id</entry>
+<entry>description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+<entry><literal>"gtk-amc_grim-guifications"</literal></entry>
+<entry>
+This is the plugin ID for the Guifications 2.x plugin.
+</entry>
+ </row>
+ <row>
+<entry><literal>"gtk-rlaager-album"</literal></entry>
+<entry>
+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.
+</entry>
+ </row>
+ <row>
+<entry><literal>"core-rlaager-irchelper"</literal></entry>
+<entry>
+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.
+</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </sect2>
- @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.
-
- </programlisting>
+ <sect2 id="plugin-ids-plugin-db">
+ <title>Plugin Database</title>
+ <para>
+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.
+ </para>
+ </sect2>
</chapter>
More information about the Commits
mailing list