SF.net SVN: geany:[5891] trunk
frlan at users.sourceforge.net
frlan at xxxxx
Fri Aug 19 06:55:34 UTC 2011
Revision: 5891
http://geany.svn.sourceforge.net/geany/?rev=5891&view=rev
Author: frlan
Date: 2011-08-19 06:55:34 +0000 (Fri, 19 Aug 2011)
Log Message:
-----------
Update of wording to fix some grammatical issues etc. on plugin howto.
Patch provided by Matthew Brush. Thanks.
Modified Paths:
--------------
trunk/ChangeLog
trunk/doc/plugins.dox
Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog 2011-08-19 00:07:41 UTC (rev 5890)
+++ trunk/ChangeLog 2011-08-19 06:55:34 UTC (rev 5891)
@@ -1,3 +1,10 @@
+2011-08-19 Frank Lanitz <frank(at)frank(dot)uvena(dot)de>
+
+ * doc/plugins.dox:
+ Update of wording to fix some grammatical issues etc. on plugin howto.
+ Patch provided by Matthew Brush. Thanks.
+
+
2011-08-19 Colomban Wendling <colomban(at)geany(dot)org>
* data/filetype_extensions.conf, data/filetypes.Cython.conf,
Modified: trunk/doc/plugins.dox
===================================================================
--- trunk/doc/plugins.dox 2011-08-19 00:07:41 UTC (rev 5890)
+++ trunk/doc/plugins.dox 2011-08-19 06:55:34 UTC (rev 5891)
@@ -194,7 +194,7 @@
* @a plugindata.h contains the biggest part of the plugin API and provides some basic macros.
* @a geanyfunctions.h provides some macros for convenient access to plugin API functions.
*
- * The you should define three basic variables which will give access to data fields and
+ * Then you should define three basic variables which will give access to data fields and
* functions provided by the plugin API.
* @code
GeanyPlugin *geany_plugin;
@@ -215,7 +215,7 @@
* For the next step, you will need to tell Geany some basic information about your plugin
* which will be shown in the plugin manager dialog.
*
- * For doing this, you should use PLUGIN_SET_INFO() which expects 4 values:
+ * To do this you should use the PLUGIN_SET_INFO() macro, which expects 4 parameters:
* - Plugin name
* - Short description
* - Version
@@ -231,7 +231,8 @@
* plugin is loaded. Part of that function could be adding and removing of an item to
* Geany's Tools menu, setting up keybindings or registering some callbacks. Also you will
* need to implement the function that is called when your plugin is unloaded.
- * These functions are called plugin_init() and plugin_cleanup(). Let's see how it could look like:
+ * These functions are called plugin_init() and plugin_cleanup(). Let's see what this
+ * looks like:
* @code
PLUGIN_VERSION_CHECK(211)
@@ -384,18 +385,18 @@
* @section furtherimprovements Furter Improvements and next steps
* @subsection translatable_plugin_information Translatable plugin information
*
- * After we have done our first plugin, there is still some place for improvements.
+ * After having written our first plugin, there is still room for improvement.
*
- * Per default PLUGIN_SET_INFO() is not allowing to translate the basic plugin
- * information for a plugin which is not shipped with Geany's core distribution.
- * In most cases, a plugin is shipped as a standalone and so it might make sense
- * to enable translation on loading time so it is localized also inside plugin manager.
- * With Geany 0.19 the plugin API is shipping the PLUGIN_SET_TRANSLATABLE_INFO()
- * macro which is enabling translation of the basic plugin details already on
- * loading time.
+ * By default, PLUGIN_SET_INFO() does not allow translation of the basic plugin
+ * information for plugins which are not shipped with Geany's core distribution.
+ * Since most plugins are not shipped with Geany's core, it makes sense to
+ * enable translation when the plugin is loaded so that it gets translated
+ * inside Geany's Plugin Manager. As of Geany 0.19, the plugin API contains
+ * the PLUGIN_SET_TRANSLATABLE_INFO() macro which enables translation of the
+ * basic plugin details passed to PLUGIN_SET_INFO() when the plugin is loaded.
*
- * PLUGIN_SET_TRANSLATABLE_INFO() is taking in difference to
- * PLUGIN_SET_INFO() two more parameters, which it makes to take 6 parameters.
+ * PLUGIN_SET_TRANSLATABLE_INFO() takes two more parameters than PLUGIN_SET_INFO(),
+ * for a total of six parameters.
*
* - Localedir
* - Gettextpackage
@@ -404,41 +405,40 @@
* - Version
* - Author
*
- * Localdir and the gettext package shall be set inside the build system.
- * If this has been done, the call for above mentioned HelloWorld-world
+ * The @a Localdir and the @a Gettextpackage parameters are usually set inside
+ * the build system. If this has been done, the call for example HelloWorld
* plugin could look like:
*
* @code
-
PLUGIN_SET_TRANSLATABLE_INFO(
LOCALEDIR, GETTEXT_PACKAGE, _("Hello World"),
_("Just another tool to say hello world"),
"1.0", "John Doe <john.doe at example.org>");
* @endcode
*
- * When using the macro, you should use the gettext macro _() to mark
+ * When using this macro, you should use the gettext macro @a _() to mark
* the strings like name and the short description as translatable as well. You
- * can see the usage inside the little example listed above.
+ * can see how this is done in the above example.
*
- * As you can see the author's informations are not marked translatable inside
- * this little example. This has been discussed onto mailing list where it has
- * been agreed to use if possible latin version of author's name
- * followed by in case of its apply able nativ spelling inside braces.
+ * As you can see the author's information is not marked as translatable in
+ * this example. The community has agreed that the best practice here is to
+ * use, if possible, the latin version of the author's name followed by the
+ * native spelling inside parenthesis, where applicable.
*
* @subsection plugin_i18n Using i18n/l10n inside Plugin
*
- * Not only the meta information of a plugin shall be translateable,
- * but also the text like menu entries, information boxes or strings
- * inside configuration dialog should be translateable too. Geany is
- * offering a way to enable this from code point of view by using a
- * function provided by the Geany API -- main_locale_init().
-
- * The function is taking over two parameters LOCALEDIR and
- * GETTEXT_PACKAGE which we already know from previous sesction.
-
- * As the function is called best on plugin initialization, it should be
- * placed into plugin_init() so the hello world example could look like:
+ * You can (and should) also mark other strings beside the plugin's meta
+ * information as translatable. Strings used in menu entries, information
+ * boxes or configuration dialogs should also be translatable as well. Geany
+ * offers a way to enable this in the plugin's code using the main_locale_init()
+ * function provided by the plugin API. This function takes the same two
+ * parameters discussed in the previous section; @a GETTEXT_PACKAGE and
+ * @a LOCALEDIR.
+ *
+ * The main_locale_init() function is best called during initialization in the
+ * plugin's plugin_init() function. Adding this to the HelloWorld example could
+ * look like:
* @code
void plugin_init(GeanyData *data)
{
@@ -452,6 +452,7 @@
}
* @endcode
*
- * If you already did use PLUGIN_SET_TRANSLATABLE_INFO() you don't need
- * to add main_locale_init() as it has already been called.
+ * @note If you've previously called the PLUGIN_SET_TRANSLATABLE_INFO() you do not
+ * need to call main_locale_init() yourself, as this has been already been
+ * done for you.
**/
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
More information about the Commits
mailing list