pidgin3: comparison doc/C-HOWTO.dox

-:a991d3324b36
+:3edb0348ba88
 C plugins are native plugins.  They have complete access to all of the api,
 and can do basically whatever they want.  All of the protocol plugins, as
 well as the perl and tcl loader plugins are written in C.
 @section getting_started Getting Started
-To develop a plugin you need to have the gaim source code.  It is generally a
+To develop a plugin you need to have the Gaim source code.  It is generally a
-good idea to compile against the same version of gaim that you are running.
+good idea to compile against the same version of Gaim that you are running.
 You may also want to develop against CVS.  While we do NOT recomend this for
-normal users, but there is an exception for developers.  A lot tends to
+normal users, it makes sense for plugin developers to use CVS to ensure their
+plugins works with the most recent changes in Gaim.  A lot tends to
 change between versions and it's much easier to fix your plugin as things
 change rather than waiting until the release.  But please do not abuse CVS.
 Gaim puts a lot of strain on Source Forge's servers, and we do not need to
 add anymore to it.
-If you choose not to head my warnings and develop against a version of gaim
+If you choose not to head my warnings and develop against a version of Gaim
-that is different from what you're running, then you're gaim source must at
+that is different from what you're running, then your Gaim source must at
 the very least be configured.  Note that just running configure will
 generally set the prefix to /usr/local.  This shouldn't be a problem, except
-that most packages compile and install gaim with /usr as the prefix.
+that most packages compile and install Gaim with /usr as the prefix.
 All plugins must have @c GAIM_PLUGINS defined.  You can choose to include
 @c internal.h to do this, but if you choose to do it this way it must be
-included before any other gaim files.  Likewise, if you choose to manually
+included before any other Gaim files.  Likewise, if you choose to manually
-define @c GAIM_PLUGINS, the definition must be before including any gaim
+define @c GAIM_PLUGINS, the definition must be before including any Gaim
 files.  Failure to do so will produce the 'plugin foo could not be loaded for
 an unknown reason'.  This is one of the hardest unknown reasons to track
 down, so let's try to avoid it at all costs ;)
 @section hello_world Hello World!
-I know every tutorial has a hello world, so why should gaim be any different?
+I know every tutorial has a hello world, so why should Gaim be any different?
 @code
 #define GAIM_PLUGINS
 #include <glib.h>
 @endcode
 Okay, so what does all this mean?  We start off by defining @c GAIM_PLUGINS
 like described before.  Next we include glib.h, mainly for gboolean and the
 glib wrappers of the standard c types.  We could just use stdio and use
-an int for the gboolean but since gaim uses  glib internally, we might as
+an int for the gboolean but since Gaim uses glib internally, we might as
 well do the same.
 Next, we include plugin.h which has all the plugin specific stuff that we
 need.  For example @c GaimPlugin, @c GaimPluginInfo, @c GAIM_PLUGIN_MAGIC,
 and @c GAIM_INIT_PLUGIN().
 Our last include is version.h which defines @c GAIM_MAJOR_VERSION, and
-@c GAIM_MINOR_VERSION.  Theres not much you need to know about these, except
+@c GAIM_MINOR_VERSION.  There is not much you need to know about these,
-that they are required and will stop your plugin from crashing Gaim when
+except that they are required and will stop your plugin from crashing Gaim
-something has changed that you plugin does not know about yet.
+when something has changed that you plugin does not know about yet.
-plugin_load is not required.  It is called when the plugin is loaded, so you
+plugin_load is not required.  It is called when the plugin is loaded so that
-can initialize any variables and so on.  But in this plugin we'll just use it
+you can initialize any variables and so on.  But in this plugin we'll just
-to display a message.
+use it to display a message.
 Next we have the @c GaimPluginInfo structure.  Every plugin MUST have one of
 these.  Below is a code snipet of the same struct used in @c hello_world with
 comments describing what each is.
 @code
 static GaimPluginInfo info = {
 	GAIM_PLUGIN_MAGIC,          /* Plugin magic, this should always be
 GAIM_PLUGIN_MAGIC.  This value gets
-incremented inside of gaim so that plugins
+incremented inside of Gaim so that plugins
-that haven't been updated yet, will fail to
+that haven't been updated yet will fail to
 load and avoid potential crashes while
 loading old plugins.
 */
-	GAIM_MAJOR_VERSION,          /* This is also define in gaim.  It helps
+	GAIM_MAJOR_VERSION,          /* This is also defined in Gaim.  It helps
-Gaim's plugin system tell what version of
+Gaim's plugin system determine what version
-this plugin was compiled for, and whether
+of Gaim this plugin was compiled for, and
-or not loading it will cause problems
+whether loading it will cause problems.
 */
 	GAIM_MINOR_VERSION,          /* See previous */
 	GAIM_PLUGIN_STANDARD,        /* GaimPluginType, there are 4 different values
 for this field.  The first is
 GAIM_PLUGIN_UNKNOWN,  which should not be
 used.  The second is GAIM_PLUGIN_STANDARD,
 this is the value most plugins will use.
 Next we have GAIM_PLUGIN_LOADER,  this is
-the type you want to load if you're plugin
+the type you want to load if your plugin
-is going to make it possible to load non
+is going to make it possible to load non-
 native plugins.  For example, perl and tcl.
 Last, we have GAIM_PLUGIN_PROTOCOL.  If
 your plugin is going to allow the user to
 connect to another network, this is the
 type you'd want to use.
 this howto.
 */
 	0,                            /* This field is for plugin flags.  Currently,
 the only flag available to plugins is
 invisible (GAIM_PLUGIN_FLAG_INVISIBLE).
-The only plugins that current use this flag,
+This plugin is currently used by the ssl
-is the ssl plugin.
+plugin, the tcl loader, and the perl
-*/
+loaded.  It causes the plugin to NOT
-	NULL,                         /* This is a glist of plugin dependencies.  In
+appear in the list of plugins in Gaim's
-other words, a glist of plugin id's that
+preferences window.
+*/
+	NULL,                         /* This is a GList of plugin dependencies.  In
+other words, a GList of plugin id's that
 your plugin depends on.  If your plugin
 does not have any dependencies, set this
-value to NULL
+value to NULL.
 */
-	GAIM_PRIORITY_DEFAULT,        /* This is the priority gaim with give your
+	GAIM_PRIORITY_DEFAULT,        /* This is the priority Gaim with give your
 plugin.  There are three possible values
 for this field, GAIM_PRIORITY_DEFAULT,
 GAIM_PRIORITY_HIGHEST, and
 GAIM_PRIORITY_LOWEST
 */
 	"core-hello_world",           /* This is your plugin's id.  There is a whole
 page dedicated to this in the
-'related-pages' section of the doxygen api.
+'related-pages' section of Gaim's API docs.
 */
 	"Hello World!",               /* This is your plugin name.  This is what
 will be displayed for your plugin in the ui.
 */
-	VERSION,                      /* This is the version of your plugin.  For
+	1.1,                          /* This is the version of your plugin.  For
-the sake of simplicity, I'm using the gaim
+the sake of simplicity, I'm using the Gaim
 version.
 */
 	"Hello World Plugin",         /* This is the summary of your plugin.  It
 should be a short little blurb.  The ui
 email address.  (You are the author right?)
 */
 	GAIM_WEBSITE,                 /* This is the website for the plugin.  This
 is helpful if users find bugs in your
 plugin so they can help to bring them to
-your attention
+your attention.
 */
-	plugin_load,                  /* This is a pointer to a function for gaim to
+	plugin_load,                  /* This is a pointer to a function for Gaim to
 call when it is loading your plugin.  It
 should be in the form of:
 gboolean function_name(GaimPlugin *plugin)
-Returning TRUE will tell gaim to continue
+Returning TRUE will tell Gaim to continue
 loading your plugin, while FALSE will tell
-gaim to stop trying to load it.
+Gaim to stop trying to load it.
 */
 	NULL,                         /* Same as above except it is called when
-gaim tries to unload your plugin.  It
+Gaim tries to unload your plugin.  It
 should be in the form of:
 gboolean function_name(GaimPlugin *plugin)
-Where returning TRUE will tell gaim to
+Where returning TRUE will tell Gaim to
 continue unloading and false to not continue
 unloading your plugin.
 */
 	NULL,                         /* Similar to the two above members, except
-this is called when gaim tries to destory
+this is called when Gaim tries to destory
 the plugin.  This is generally only called
 when for some reason or another the plugin
 fails to probe correctly.  It should be in
 the form of:
 @endcode
 Finally we have @c init_plugin and @c GAIM_INIT_PLUGIN.  @c init_plugin is a
 function that gets called when Gaim probes the plugin.  Most plugins will
 add their preferences to the pref tree here, more about that later.
-@GAIM_INIT_PLUGIN is a macro that EVERY plugin MUST have.  @GAIM_INIT_PLUGIN
+@c GAIM_INIT_PLUGIN is a macro that EVERY plugin MUST have.  @c GAIM_INIT_PLUGIN
-tells gaim some very basic things about your plugin, like what name to use
+tells Gaim some very basic things about your plugin, like what name to use
 if the plugin is compiled staticly, the @c init_plugin function, and
 the name of the @c GaimPluginInfo structure.  As you may have guess this
 also gets read when Gaim is probing your plugin.  If this is missing you
 will get the infamous "plugin unloadable for unknown reasons", so do not
 forget it.

Mercurial > pidgin3 / file comparison

comparison: doc/C-HOWTO.dox

doc/C-HOWTO.dox