/soc/2013/ankitkv/gobjectification: 1c4efce838f6: gtk-doc-ify C-...
Ankit Vani
a at nevitus.org
Sat Feb 8 10:07:18 EST 2014
Changeset: 1c4efce838f6b76ddff752124065c6e2d8fd2499
Author: Ankit Vani <a at nevitus.org>
Date: 2014-02-08 20:23 +0530
Branch: gtkdoc-conversion
URL: https://hg.pidgin.im/soc/2013/ankitkv/gobjectification/rev/1c4efce838f6
Description:
gtk-doc-ify C-HOWTO, plugin-i18n, plugin-ids, plugin-signals
diffstat:
doc/reference/libpurple/libpurple-docs.xml | 4 +
doc/plugin-i18n.dox | 234 ++++++++++++++++--------
doc/plugin-ids.dox | 270 +++++++++++++++++++---------
doc/plugin-signals.dox | 82 ++++++--
doc/C-HOWTO.dox | 102 +++++++---
libpurple/plugin.h | 3 +
6 files changed, 468 insertions(+), 227 deletions(-)
diffs (truncated from 831 to 300 lines):
diff --git a/doc/reference/libpurple/libpurple-docs.xml b/doc/reference/libpurple/libpurple-docs.xml
--- a/doc/reference/libpurple/libpurple-docs.xml
+++ b/doc/reference/libpurple/libpurple-docs.xml
@@ -21,6 +21,7 @@
<part label="I">
<title>Tutorials</title>
+ <xi:include href="tut_c_plugins.xml" />
<xi:include href="tut_signals.xml" />
</part>
@@ -147,12 +148,15 @@
<xi:include href="signals_xfer.xml" />
<xi:include href="signals_log.xml" />
<xi:include href="signals_notify.xml" />
+ <xi:include href="signals_plugin.xml" />
<xi:include href="signals_savedstatus.xml" />
<xi:include href="signals_sound.xml" />
<xi:include href="signals_imgstore.xml" />
<xi:include href="signals_jabber.xml" />
</reference>
+ <xi:include href="plugin_ids.xml" />
+ <xi:include href="plugin_i18n.xml" />
<xi:include href="ui_ops.xml" />
<index id="api-index-full">
diff --git a/doc/plugin-i18n.dox b/doc/reference/libpurple/plugin_i18n.xml
rename from doc/plugin-i18n.dox
rename to doc/reference/libpurple/plugin_i18n.xml
--- a/doc/plugin-i18n.dox
+++ b/doc/reference/libpurple/plugin_i18n.xml
@@ -1,107 +1,177 @@
-/** @page plugin-i18n Third Party Plugin Translation Support
+<?xml version='1.0' encoding="ISO-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<chapter id="chapter-plugin-i18n">
+ <title>Third Party Plugin Translation</title>
- @section Introduction
+ <sect2 id="plugin-i18n-introduction">
+ <title>Introduction</title>
+
+ <para>
For the purpose of this document we're going to assume that your plugin:
- - Is set up to use autotools. It may be possible to add translation support
- without autotools, but we have no idea how. We may not want to know, either ;)
- - Has an autogen.sh. You may have also called this bootstrap.sh or similar.
- - Resides in a source tree that has @c configure.ac and @c Makefile.am in the
- top-level directory as well as a @c src directory in which the plugin's source
- is located. A @c Makefile.am should also exist in the @c src directory.
+ <itemizedlist>
+ <listitem><para>
+Is set up to use autotools. It may be possible to add translation support
+without autotools, but we have no idea how. We may not want to know, either ;)
+ </para></listitem>
+ <listitem><para>
+Has an autogen.sh. You may have also called this bootstrap.sh or similar.
+ </para></listitem>
+ <listitem><para>
+Resides in a source tree that has <literal>configure.ac</literal> and
+<literal>Makefile.am</literal> in the top-level directory as well as a
+<literal>src</literal> directory in which the plugin's source is located. A
+<literal>Makefile.am</literal> should also exist in the <literal>src</literal>
+directory.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+ <sect2 id="plugin-i18n-steps">
+ <title>Steps to follow</title>
+
+ <para>
For a plugin to have translation support there are a few steps that need to
followed:
- - In your autogen.sh, add the following after your other utility checks:
- @code
-(intltoolize --version) < /dev/null > /dev/null 2>&1 || {
+ <itemizedlist>
+ <listitem><para>
+In your autogen.sh, add the following after your other utility checks:
+<programlisting>
+(intltoolize --version) < /dev/null > /dev/null 2>&1 || {
echo;
- echo "You must have intltool installed to compile <YOUR PLUGIN NAME>";
+ echo "You must have intltool installed to compile <YOUR PLUGIN NAME>";
echo;
exit;
}
- @endcode
- Then before your call to aclocal add:
- @code
+</programlisting>
+Then before your call to aclocal add:
+<programlisting>
intltoolize --force --copy
- @endcode
- - Now edit configure.ac and add the following:
- @code
+</programlisting>
+ </para></listitem>
+ <listitem><para>
+Now edit configure.ac and add the following:
+<programlisting>
AC_PROG_INTLTOOL
-GETTEXT_PACKAGE=<YOUR PLUGIN NAME>
+GETTEXT_PACKAGE=<YOUR PLUGIN NAME>
AC_SUBST(GETTEXT_PACKAGE)
AC_DEFINE_UNQUOTED(GETTEXT_PACKAGE, ["$GETTEXT_PACKAGE"], [Define the gettext package to be used])
ALL_LINGUAS=""
AM_GLIB_GNU_GETTEXT
- @endcode
- The position of these macros in the file don't really matter, but if you
- have issues either play around with it or feel free to ask one of the Pidgin
- developers. Finally add 'po/Makefile.in' to you 'AC_OUTPUT' command.
- - Now create a directory named 'po'.
- - 'cd' into the 'po' directory.
- - Create/edit the file 'POTFILE.in' in your favorite editor. Each line
- should be the name of a file that could or does have strings marked for
- translating (we're getting to that step). These file names should be
- relative to the top directory of your plugin's source tree.
- - 'cd' back to the top directory of your plugin's source tree.
- - Open 'Makefile.am' and add 'po' to your 'SUBDIRS' variable.
- - While still in the top directory of your plugin's source tree, execute
- 'intltool-prepare'. This will setup anything extra that intltool needs.
- - Fire off 'autogen.sh' and when it's completed, verify that you have a
- 'po/POTFILES' (notice the lack of a .in). If you do, everything should be
- set on the autotools side.
- - Take a break, stretch your legs, smoke a cigarette, whatever, because
- we're done with the autotools part.
- - When you're ready, 'cd' into the directory with the source files for your
- plugin.
- - Open the file containing the PurplePluginInfo structure.
- - If you're not already, please make sure that you are including the
- 'config.h' file for you plugin. Note that 'config.h' could be whatever
- you told autohead to use with AM_CONFIG_HEADER. Also add the following:
- @code
-#include <glib/gi18n-lib.h>
- @endcode
- Make sure that this include is after you include of your 'config.h',
- otherwise you will break your build. Also note that if you wish to
- maintain compatibility with older versions of GLib, you will need to
- include additional preprocessor directives, which we won't cover here.
- - This is where things get a bit goofy. libpurple is going to try to
- translate our strings using the libpurple gettext package. So we have to
- convert them before libpurple attempts to.
- - To do this, we're going to change the entries for name, summary, and
- description to NULL.
- - Next, locate your 'init_plugin' function. Your name for this function
- may vary, but it's the second parameter to 'PURPLE_INIT_PLUGIN'.
- - Now add the following within your 'init_plugin' function:
- @code
+</programlisting>
+The position of these macros in the file don't really matter, but if you
+have issues either play around with it or feel free to ask one of the Pidgin
+developers. Finally add 'po/Makefile.in' to you 'AC_OUTPUT' command.
+ </para></listitem>
+ <listitem><para>
+Now create a directory named 'po'.
+ </para></listitem>
+ <listitem><para>
+'cd' into the 'po' directory.
+ </para></listitem>
+ <listitem><para>
+Create/edit the file 'POTFILE.in' in your favorite editor. Each line
+should be the name of a file that could or does have strings marked for
+translating (we're getting to that step). These file names should be
+relative to the top directory of your plugin's source tree.
+ </para></listitem>
+ <listitem><para>
+'cd' back to the top directory of your plugin's source tree.
+ </para></listitem>
+ <listitem><para>
+Open 'Makefile.am' and add 'po' to your 'SUBDIRS' variable.
+ </para></listitem>
+ <listitem><para>
+While still in the top directory of your plugin's source tree, execute
+'intltool-prepare'. This will setup anything extra that intltool needs.
+ </para></listitem>
+ <listitem><para>
+Fire off 'autogen.sh' and when it's completed, verify that you have a
+'po/POTFILES' (notice the lack of a .in). If you do, everything should be
+set on the autotools side.
+ </para></listitem>
+ <listitem><para>
+Take a break, stretch your legs, smoke a cigarette, whatever, because
+we're done with the autotools part.
+ </para></listitem>
+ <listitem><para>
+When you're ready, 'cd' into the directory with the source files for your
+plugin.
+ </para></listitem>
+ <listitem><para>
+Open the file containing the PurplePluginInfo structure.
+ </para></listitem>
+ <listitem><para>
+If you're not already, please make sure that you are including the
+'config.h' file for you plugin. Note that 'config.h' could be whatever
+you told autohead to use with AM_CONFIG_HEADER. Also add the following:
+<programlisting>
+#include <glib/gi18n-lib.h>
+</programlisting>
+Make sure that this include is after you include of your 'config.h',
+otherwise you will break your build. Also note that if you wish to
+maintain compatibility with older versions of GLib, you will need to
+include additional preprocessor directives, which we won't cover here.
+ </para></listitem>
+ <listitem><para>
+This is where things get a bit goofy. libpurple is going to try to
+translate our strings using the libpurple gettext package. So we have to
+convert them before libpurple attempts to.
+ </para></listitem>
+ <listitem><para>
+To do this, we're going to change the entries for name, summary, and
+description to NULL.
+ </para></listitem>
+ <listitem><para>
+Next, locate your 'init_plugin' function. Your name for this function
+may vary, but it's the second parameter to 'PURPLE_INIT_PLUGIN'.
+ </para></listitem>
+ <listitem><para>
+Now add the following within your 'init_plugin' function:
+<programlisting>
#ifdef ENABLE_NLS
bindtextdomain(GETTEXT_PACKAGE, LOCALEDIR);
bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8");
#endif /* ENABLE_NLS */
- info.name = _("<YOUR PLUGIN NAME>");
- info.summary = _("<YOUR PLUGIN SUMMARY>");
- info.description = _("<YOUR PLUGIN DESCRIPTION>");
- @endcode
- Note that the _() is intentional, and that it is telling intltool that
- this string should be translated. There is also N_() which says that a
- string should only be marked for translation but should not be translated
- yet.
- - Go through the rest of your code and mark all the other strings for
- translation with _().
- - When thats done, feel free to commit your work, create your po template
- (pot file) or whatever.
- - To create you po template, 'cd' to 'po' and execute:
- @code
+ info.name = _("<YOUR PLUGIN NAME>");
+ info.summary = _("<YOUR PLUGIN SUMMARY>");
+ info.description = _("<YOUR PLUGIN DESCRIPTION>");
+</programlisting>
+Note that the _() is intentional, and that it is telling intltool that
+this string should be translated. There is also N_() which says that a
+string should only be marked for translation but should not be translated
+yet.
+ </para></listitem>
+ <listitem><para>
+Go through the rest of your code and mark all the other strings for
+translation with _().
+ </para></listitem>
+ <listitem><para>
+When thats done, feel free to commit your work, create your po template
+(pot file) or whatever.
+ </para></listitem>
+ <listitem><para>
+To create you po template, 'cd' to 'po' and execute:
+<programlisting>
intltool-update --pot
- @endcode
- - To add new translations to your plugin, all you have to do is add the
- language code to the 'ALL_LINGUAS' variable in your configure.ac. Take
- note that this list of languages should be separated by a space. After
- you have added the language code to 'ALL_LINGUAS', drop the xx.po file
- into 'po', and re-'autogen.sh'. After a full build you should now be
- able to use the translation.
- */
+</programlisting>
+ </para></listitem>
+ <listitem><para>
+To add new translations to your plugin, all you have to do is add the
+language code to the 'ALL_LINGUAS' variable in your configure.ac. Take
+note that this list of languages should be separated by a space. After
+you have added the language code to 'ALL_LINGUAS', drop the xx.po file
+into 'po', and re-'autogen.sh'. After a full build you should now be
+able to use the translation.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+</chapter>
diff --git a/doc/plugin-ids.dox b/doc/reference/libpurple/plugin_ids.xml
rename from doc/plugin-ids.dox
rename to doc/reference/libpurple/plugin_ids.xml
--- a/doc/plugin-ids.dox
+++ b/doc/reference/libpurple/plugin_ids.xml
@@ -1,100 +1,198 @@
-/** @page plugin-ids Plugin IDs
+<?xml version='1.0' encoding="ISO-8859-1"?>
More information about the Commits
mailing list