HybridDog/geany
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update of wording to fix some grammatical issues etc. on plugin howto.

Browse Source 
Patch provided by Matthew Brush. Thanks.

git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@5891 ea778897-0a13-0410-b9d1-a72fbfd435f5
This commit is contained in:
Frank Lanitz 2011-08-19 06:55:34 +00:00
parent 9d2975b8fa
commit a2ef453ea3
2 changed files with 43 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
ChangeLog
View File

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

71
doc/plugins.dox
View File

@ -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 @@ GeanyFunctions *geany_functions;
* 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_SET_INFO("HelloWorld", "Just another tool to say hello world",
* 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 @@ void plugin_cleanup(void)
* @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 @@ void plugin_cleanup(void)
* - 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 @@ void plugin_init(GeanyData *data)
}
* @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.
**/