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@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.