Branch: refs/heads/master Author: Matthew Brush matt@geany.org Committer: Matthew Brush matt@geany.org Date: Sun, 27 Apr 2014 10:53:59 UTC Commit: 5475d15b87ad45bfbe266eaddf3ef854dfa3b62b https://github.com/geany/geany/commit/5475d15b87ad45bfbe266eaddf3ef854dfa3b6...

Log Message: ----------- Remove comment noise from `doc/plugins.dox` and make it a build depend

Modified Paths: -------------- doc/Makefile.am doc/plugins.dox

Modified: doc/Makefile.am 1 lines changed, 1 insertions(+), 0 deletions(-) =================================================================== @@ -52,6 +52,7 @@ if WITH_DOXYGEN

doxygen_sources = \ $(srcdir)/*.[ch] \ + $(srcdir)/*.dox \ $(top_srcdir)/src/*.[ch] \ $(top_srcdir)/plugins/geanyplugin.h \ $(top_srcdir)/plugins/geanyfunctions.h \

Modified: doc/plugins.dox 712 lines changed, 356 insertions(+), 356 deletions(-) =================================================================== @@ -1,235 +1,234 @@ /* - * plugins.dox - this file is part of Geany, a fast and lightweight IDE + * plugins.dox - this file is part of Geany, a fast and lightweight IDE * - * Copyright 2008-2011 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de> - * Copyright 2008-2011 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com> - * Copyright 2009-2012 Frank Lanitz <frank(at)frank(dot)uvena(dot)de> + * Copyright 2008-2011 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de> + * Copyright 2008-2011 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com> + * Copyright 2009-2012 Frank Lanitz <frank(at)frank(dot)uvena(dot)de> + * Copyright 2014 Matthew Brush <matt(at)geany(dot)org> * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. * - * You should have received a copy of the GNU General Public License along - * with this program; if not, write to the Free Software Foundation, Inc., - * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. * - * This file contains additional plugin documentation like the signal system and a small howto. - * It is best viewed when filetype is set to C or C++. + * This file contains additional plugin documentation like the signal system + * and a small howto. It is best viewed when filetype is set to C or C++. */

/** - * - * @mainpage Geany Plugin API Documentation - * - * @author Enrico Tröger, Nick Treleaven, Frank Lanitz - * - * @section Intro - * This is the Geany API documentation. It should be considered work in progress. - * We will try to document as many functions and structs as possible. - * - * @warning Do not use any symbol not in the documentation - it may change. - * - * @section pluginsupport Plugin Support - * - @link howto Plugin HowTo @endlink - get started - * - @link pluginsymbols.c Plugin Symbols @endlink - * - @link plugindata.h Plugin Datatypes and Macros @endlink - * - @link pluginsignals.c Plugin Signals @endlink - * - @link pluginutils.h Plugin Utility Functions @endlink - * - @link guidelines Plugin Writing Guidelines @endlink - * - <b>plugins/demoplugin.c</b> - in Geany's source, bigger than the howto example - * - * @section common Common API files - * - @link dialogs.h @endlink - * - @link document.h @endlink - * - @link editor.h @endlink - * - @link filetypes.h @endlink - * - @link keybindings.h @endlink - * - @link msgwindow.h @endlink - * - @link project.h @endlink - * - @link sciwrappers.h Scintilla Wrapper Functions @endlink - * - @link stash.h Stash Pref/Setting Functions @endlink - * - @link utils.h General Utility Functions @endlink - * - @link ui_utils.h Widget Utility Functions @endlink - - * @section More - * - All API functions and types - see <b>Files</b> link at the top - * - Deprecated symbols - see <b>Related Pages</b> link at the top - * - * @note See the HACKING file for information about developing the plugin API and - * other useful notes. - */

-/** - * @page guidelines Plugin Writing Guidelines - * - * @section intro Introduction - * - * The following hints and guidelines are only recommendations. Nobody is forced to follow - * them at all. - * - * @section general General notes - * - * @subsection ideas Getting a plugin idea - * - * If you want to write a plugin but don't know yet what it should do, have a look at - * http://www.geany.org/Support/PluginWishlist to get an idea about what users wish. - * - * @subsection code Managing the source code - * - * For authors of plugins for Geany, we created a dedicated @a geany-plugins project - * on Sourceforge and GitHub to ease development of plugins and help new authors. - * All information about this project you can find at http://plugins.geany.org/ - * - * To add a new plugin to this project, get in touch with the people on the - * geany-devel-mailing list and create a fork of the geany-plugins project - * at https://github.com/geany/geany-plugins. - * Beside of adding a new plugin, geany-devel-mailing list is also the place where - * to discuss development related questions. - * However, once you have done your fork of geany-plugins you can develop - * your plugin until you think its the right time to publish it. At this point, - * create a pull request for adding your patch set into the master branch of the main - * geany-plugins repository. - * - * Of course, you don't need to use GitHub - any Git is fine. But GitHub - * is making it way easier for review, merging and get in touch with you for - * comments. - * - * If you don't want your plugin to be part of the geany-plugins project it is also fine. - * Just skip the part about forking geany-plugins and sending a pull request. - * In this case it is of course also a good idea to post some kind of announcement - * to geany-devel and maybe to the main geany mailing list -- it's up to you. - * You can also ask for your plugin to be listed on the http://plugins.geany.org/ - * website as a third party plugin, helping Geany user to know about your plugin. - * - * At time of writing, there are some plugins already available in the - * repositories. Feel free to use any of these plugins as a start for your own, - * maybe by copying the directory structure and the autotools files - * (Makefile.am, configure.in, ...). Most of the available plugins are also ready for - * i18n support, just for reference. - * - * We encourage authors using this service to only commit changes to their - * own plugin and not to others' plugins. Instead just send patches to - * geany-devel at uvena.de or the plugin author directly. - * - * @section paths Installation paths - * - * - The plugin binary (@c pluginname.so) should be installed in Geany's libdir. This is - * necessary so that Geany can find the plugin. - * An easy way to retrieve Geany's libdir is to use the pkg-config tool, e.g. @code - * `$PKG_CONFIG --variable=libdir geany`/ geany - * @endcode - * - If your plugin creates other binary files like helper programs or helper libraries, - * they should go into @c $prefix/bin (for programs, ideally prefixed with @a geany), - * additional libraries should be installed in Geany's libdir, maybe in a subdirectory. - * - Plugins should install their documentation files (README, NEWS, ChangeLog, licences and - * other documentation files) into the common documentation directory - * @c $prefix/share/doc/geany-plugins/$pluginname/ - * - Translation files should be installed normally into @c $prefix/share/locale. There is no - * need to use Geany's translation directory. To set up translation support properly and - * for additional information, see main_locale_init(). - * - Do @a never install anything into a user's home directory like installing - * the plugin binary in @c ~/.config/geany/plugins/. - * - * - * @page howto Plugin HowTo - * - * @section intro Introduction - * - * Since Geany 0.12 there is a plugin interface to extend Geany's functionality and - * add new features. This document gives a brief overview about how to add new - * plugins by writing a simple "Hello World" plugin in C or C++. - * - * - * @section buildenv Build environment - * - * To be able to write plugins for Geany, you need the source code and some development - * packages for GTK and its dependencies. The following will only describe the way to compile and - * build plugins on Unix-like systems [1]. - * If you already have the Geany source code and compiled it from them, you can skip the - * following. - * - * First you need to have Geany installed. Then install the development files for GTK - * and its dependencies. The easiest way to do this is to use your distribution's package - * management system, e.g. on Debian and Ubuntu systems you can use - * @code apt-get install libgtk2.0-dev intltool @endcode - * This will install all necessary files to be able to compile plugins for Geany. On other - * distributions, the package names and commands to use may differ. - * - * Basically, you are done at this point and could continue with writing the plugin code. - * - * [1] For Windows, it is basically the same but you might have some more work on setting up - * the general build environment(compiler, GTK development files, ...). This is described on - * Geany's website at http://www.geany.org/Support/BuildingOnWin32. - * - * @section helloworld "Hello World" - * - * When writing a plugin, you will find a couple of functions or macros which are mandatory - * and some which are free to use for implementing some useful feature once your plugin - * becomes more powerful like including a configuration or help dialog. - * - * You should start your plugin with including some of the needed C header files and defining - * some basic global variables which will help you to access all needed functions of the plugin - * API in a more comfortable way. - * - * Let's start with the very basic headers and add more later if necessary. - * @code +@mainpage Geany Plugin API Documentation + +@author Enrico Tröger, Nick Treleaven, Frank Lanitz, Matthew Brush + +@section Intro +This is the Geany API documentation. It should be considered work in progress. +We will try to document as many functions and structs as possible. + +@warning Do not use any symbol not in the documentation - it may change. + +@section pluginsupport Plugin Support +- @link howto Plugin HowTo @endlink - get started +- @link pluginsymbols.c Plugin Symbols @endlink +- @link plugindata.h Plugin Datatypes and Macros @endlink +- @link pluginsignals.c Plugin Signals @endlink +- @link pluginutils.h Plugin Utility Functions @endlink +- @link guidelines Plugin Writing Guidelines @endlink +- <b>plugins/demoplugin.c</b> - in Geany's source, bigger than the howto example + +@section common Common API files +- @link dialogs.h @endlink +- @link document.h @endlink +- @link editor.h @endlink +- @link filetypes.h @endlink +- @link keybindings.h @endlink +- @link msgwindow.h @endlink +- @link project.h @endlink +- @link sciwrappers.h Scintilla Wrapper Functions @endlink +- @link stash.h Stash Pref/Setting Functions @endlink +- @link utils.h General Utility Functions @endlink +- @link ui_utils.h Widget Utility Functions @endlink + +@section More +- All API functions and types - see <b>Files</b> link at the top +- Deprecated symbols - see <b>Related Pages</b> link at the top + +@note See the HACKING file for information about developing the plugin API and +other useful notes. + +@page guidelines Plugin Writing Guidelines + +@section intro Introduction + +The following hints and guidelines are only recommendations. Nobody is forced to follow +them at all. + +@section general General notes + +@subsection ideas Getting a plugin idea + +If you want to write a plugin but don't know yet what it should do, have a look at +http://www.geany.org/Support/PluginWishlist to get an idea about what users wish. + +@subsection code Managing the source code + +For authors of plugins for Geany, we created a dedicated @a geany-plugins project +on Sourceforge and GitHub to ease development of plugins and help new authors. +All information about this project you can find at http://plugins.geany.org/ + +To add a new plugin to this project, get in touch with the people on the +geany-devel-mailing list and create a fork of the geany-plugins project +at https://github.com/geany/geany-plugins. +Beside of adding a new plugin, geany-devel-mailing list is also the place where +to discuss development related questions. +However, once you have done your fork of geany-plugins you can develop +your plugin until you think its the right time to publish it. At this point, +create a pull request for adding your patch set into the master branch of the main +geany-plugins repository. + +Of course, you don't need to use GitHub - any Git is fine. But GitHub +is making it way easier for review, merging and get in touch with you for +comments. + +If you don't want your plugin to be part of the geany-plugins project it is also fine. +Just skip the part about forking geany-plugins and sending a pull request. +In this case it is of course also a good idea to post some kind of announcement +to geany-devel and maybe to the main geany mailing list -- it's up to you. +You can also ask for your plugin to be listed on the http://plugins.geany.org/ +website as a third party plugin, helping Geany user to know about your plugin. + +At time of writing, there are some plugins already available in the +repositories. Feel free to use any of these plugins as a start for your own, +maybe by copying the directory structure and the autotools files +(Makefile.am, configure.in, ...). Most of the available plugins are also ready for +i18n support, just for reference. + +We encourage authors using this service to only commit changes to their +own plugin and not to others' plugins. Instead just send patches to +geany-devel at uvena.de or the plugin author directly. + +@section paths Installation paths + +- The plugin binary (@c pluginname.so) should be installed in Geany's libdir. This is + necessary so that Geany can find the plugin. + An easy way to retrieve Geany's libdir is to use the pkg-config tool, e.g. @code + `$PKG_CONFIG --variable=libdir geany`/ geany + @endcode +- If your plugin creates other binary files like helper programs or helper libraries, + they should go into @c $prefix/bin (for programs, ideally prefixed with @a geany), + additional libraries should be installed in Geany's libdir, maybe in a subdirectory. +- Plugins should install their documentation files (README, NEWS, ChangeLog, licences and + other documentation files) into the common documentation directory + @c $prefix/share/doc/geany-plugins/$pluginname/ +- Translation files should be installed normally into @c $prefix/share/locale. There is no + need to use Geany's translation directory. To set up translation support properly and + for additional information, see main_locale_init(). +- Do @a never install anything into a user's home directory like installing + the plugin binary in @c ~/.config/geany/plugins/. + + +@page howto Plugin HowTo + +@section intro Introduction + +Since Geany 0.12 there is a plugin interface to extend Geany's functionality and +add new features. This document gives a brief overview about how to add new +plugins by writing a simple "Hello World" plugin in C or C++. + + +@section buildenv Build environment + +To be able to write plugins for Geany, you need the source code and some development +packages for GTK and its dependencies. The following will only describe the way to compile and +build plugins on Unix-like systems [1]. +If you already have the Geany source code and compiled it from them, you can skip the +following. + +First you need to have Geany installed. Then install the development files for GTK +and its dependencies. The easiest way to do this is to use your distribution's package +management system, e.g. on Debian and Ubuntu systems you can use +@code apt-get install libgtk2.0-dev intltool @endcode +This will install all necessary files to be able to compile plugins for Geany. On other +distributions, the package names and commands to use may differ. + +Basically, you are done at this point and could continue with writing the plugin code. + +[1] For Windows, it is basically the same but you might have some more work on setting up +the general build environment(compiler, GTK development files, ...). This is described on +Geany's website at http://www.geany.org/Support/BuildingOnWin32. + +@section helloworld "Hello World" + +When writing a plugin, you will find a couple of functions or macros which are mandatory +and some which are free to use for implementing some useful feature once your plugin +becomes more powerful like including a configuration or help dialog. + +You should start your plugin with including some of the needed C header files and defining +some basic global variables which will help you to access all needed functions of the plugin +API in a more comfortable way. + +Let's start with the very basic headers and add more later if necessary. +@code #include <geanyplugin.h> - * @endcode - * - * @a geanyplugin.h includes all of the Geany API and also the necessary GTK header files, - * so there is no need to include @a gtk/gtk.h yourself. - * - * @note - * @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. - * - * Then you should define three basic variables which will give access to data fields and - * functions provided by the plugin API. - * @code +@endcode + +@a geanyplugin.h includes all of the Geany API and also the necessary GTK header files, +so there is no need to include @a gtk/gtk.h yourself. + +@note +@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. + +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; GeanyData *geany_data; GeanyFunctions *geany_functions; - * @endcode - * - * Now you can go on and write your first lines for your new plugin. As mentioned before, - * you will need to implement and fill out a couple of functions/macros to make the plugin work. - * So let's start with PLUGIN_VERSION_CHECK(). - * - * PLUGIN_VERSION_CHECK() is a convenient way to tell Geany which version of Geany's plugin API - * is needed at minimum to run your plugin. The value is defined in - * @a plugindata.h by @a GEANY_API_VERSION. In most cases this should be your minimum. - * Nevertheless when setting this value, you should choose the lowest possible version here to - * make the plugin compatible with a bigger number of versions of Geany. - * - * 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. - * - * To do this you should use the PLUGIN_SET_INFO() macro, which expects 4 parameters: - * - Plugin name - * - Short description - * - Version - * - Author - * - * Based on this, the line could look like: - * @code +@endcode + +Now you can go on and write your first lines for your new plugin. As mentioned before, +you will need to implement and fill out a couple of functions/macros to make the plugin work. +So let's start with PLUGIN_VERSION_CHECK(). + +PLUGIN_VERSION_CHECK() is a convenient way to tell Geany which version of Geany's plugin API +is needed at minimum to run your plugin. The value is defined in +@a plugindata.h by @a GEANY_API_VERSION. In most cases this should be your minimum. +Nevertheless when setting this value, you should choose the lowest possible version here to +make the plugin compatible with a bigger number of versions of Geany. + +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. + +To do this you should use the PLUGIN_SET_INFO() macro, which expects 4 parameters: +- Plugin name +- Short description +- Version +- Author + +Based on this, the line could look like: +@code PLUGIN_SET_INFO("HelloWorld", "Just another tool to say hello world", "1.0", "John Doe john.doe@example.org"); - * @endcode - * - * Once this is done, you will need to implement the function which will be executed when the - * 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 what this - * looks like: - * @code +@endcode + +Once this is done, you will need to implement the function which will be executed when the +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 what this +looks like: +@code PLUGIN_VERSION_CHECK(211)

PLUGIN_SET_INFO("HelloWorld", "Just another tool to say hello world", @@ -242,19 +241,19 @@ void plugin_init(GeanyData *data) void plugin_cleanup(void) { } - * @endcode - * - * If you think this plugin seems not to implement any functionality right now and only wastes - * some memory, you are right. But it should compile and load/unload in Geany nicely. - * Now you have the very basic layout of a new plugin. Great, isn't it? - * - * @note - * - * If you would rather write the plugin in C++, you can do that by marking the - * plugin functions that it implements as @c extern @c "C", for example: - * - * @code - * +@endcode + +If you think this plugin seems not to implement any functionality right now and only wastes +some memory, you are right. But it should compile and load/unload in Geany nicely. +Now you have the very basic layout of a new plugin. Great, isn't it? + +@note + +If you would rather write the plugin in C++, you can do that by marking the +plugin functions that it implements as @c extern @c "C", for example: + +@code + extern "C" void plugin_init(GeanyData *data) { } @@ -262,34 +261,34 @@ extern "C" void plugin_init(GeanyData *data) extern "C" void plugin_cleanup(void) { } - * @endcode - * - * @section building Building - * - * First make plugin.o: - * - * @code gcc -c plugin.c -fPIC `pkg-config --cflags geany` @endcode - * - * Then make the plugin library plugin.so (or plugin.dll on Windows): - * - * @code gcc plugin.o -o plugin.so -shared `pkg-config --libs geany` @endcode - * - * If all went OK, put the library into one of the paths Geany looks for plugins, - * e.g. $prefix/lib/geany. See @ref paths "Installation paths" for details. - * - * @note - * - * If you are writing the plugin in C++, then you will need to use your C++ - * compiler here, for example @c g++. - * - * @section realfunc Adding functionality - * - * Let's go on and implement some real functionality. - * - * As mentioned before, plugin_init() will be called when the plugin is loaded in Geany. - * So it should implement everything that needs to be done during startup. In this case, - * we'd like to add a menu item to Geany's Tools menu which runs a dialog printing "Hello World". - * @code +@endcode + +@section building Building + +First make plugin.o: + +@code gcc -c plugin.c -fPIC `pkg-config --cflags geany` @endcode + +Then make the plugin library plugin.so (or plugin.dll on Windows): + +@code gcc plugin.o -o plugin.so -shared `pkg-config --libs geany` @endcode + +If all went OK, put the library into one of the paths Geany looks for plugins, +e.g. $prefix/lib/geany. See @ref paths "Installation paths" for details. + +@note + +If you are writing the plugin in C++, then you will need to use your C++ +compiler here, for example @c g++. + +@section realfunc Adding functionality + +Let's go on and implement some real functionality. + +As mentioned before, plugin_init() will be called when the plugin is loaded in Geany. +So it should implement everything that needs to be done during startup. In this case, +we'd like to add a menu item to Geany's Tools menu which runs a dialog printing "Hello World". +@code void plugin_init(GeanyData *data) { GtkWidget *main_menu_item; @@ -307,36 +306,36 @@ void plugin_init(GeanyData *data) g_signal_connect(main_menu_item, "activate", G_CALLBACK(item_activate_cb), NULL); } - * @endcode - * - * This will add an item to the Tools menu and connect this item to a function which implements - * what should be done when the menu item is activated by the user. - * This is done by g_signal_connect(). The Tools menu can be accessed with - * geany->main_widgets->tools_menu. The structure @a main_widgets contains pointers to the - * main GUI elements in Geany. - * - * Geany has a simple API for showing message dialogs. So our function contains - * only a few lines: - * @code +@endcode + +This will add an item to the Tools menu and connect this item to a function which implements +what should be done when the menu item is activated by the user. +This is done by g_signal_connect(). The Tools menu can be accessed with +geany->main_widgets->tools_menu. The structure @a main_widgets contains pointers to the +main GUI elements in Geany. + +Geany has a simple API for showing message dialogs. So our function contains +only a few lines: +@code void item_activate_cb(GtkMenuItem *menuitem, gpointer user_data) { dialogs_show_msgbox(GTK_MESSAGE_INFO, "Hello World"); } - * @endcode - * - * For the moment you don't need to worry about the parameters of that function. - * - * Now we need to clean up properly when the plugin is unloaded. - * - * To remove the menu item from the Tools menu, you can use gtk_widget_destroy(). - * gtk_widget_destroy() expects a pointer to a GtkWidget object. - * - * First you should add gtk_widget_destroy() to your plugin_cleanup() function. - * The argument for gtk_widget_destroy() is the widget object you created earlier in - * plugin_init(). To be able to access this pointer in plugin_cleanup(), you need to move - * its definition from plugin_init() into the global context so its visibility will increase - * and it can be accessed in all functions. - * @code +@endcode + +For the moment you don't need to worry about the parameters of that function. + +Now we need to clean up properly when the plugin is unloaded. + +To remove the menu item from the Tools menu, you can use gtk_widget_destroy(). +gtk_widget_destroy() expects a pointer to a GtkWidget object. + +First you should add gtk_widget_destroy() to your plugin_cleanup() function. +The argument for gtk_widget_destroy() is the widget object you created earlier in +plugin_init(). To be able to access this pointer in plugin_cleanup(), you need to move +its definition from plugin_init() into the global context so its visibility will increase +and it can be accessed in all functions. +@code static GtkWidget *main_menu_item = NULL;

// ... @@ -351,15 +350,15 @@ void plugin_cleanup(void) { gtk_widget_destroy(main_menu_item); } - * @endcode - * - * This will ensure your menu item is removed from the Tools menu as well as from - * memory once your plugin is unloaded, so you don't leave any memory leaks. - * Once this is done, your first plugin is ready. Congratulations! - * - * @section listing Complete listing (without comments) - * - * @code +@endcode + +This will ensure your menu item is removed from the Tools menu as well as from +memory once your plugin is unloaded, so you don't leave any memory leaks. +Once this is done, your first plugin is ready. Congratulations! + +@section listing Complete listing (without comments) + +@code #include <geanyplugin.h>

GeanyPlugin *geany_plugin; @@ -393,70 +392,70 @@ void plugin_cleanup(void) { gtk_widget_destroy(main_menu_item); } - * @endcode - * - * - * Now you might like to look at Geany's source code for core plugins such as - * @a plugins/demoplugin.c. - * - * @section furtherimprovements Furter Improvements and next steps - * @subsection translatable_plugin_information Translatable plugin information - * - * After having written our first plugin, there is still room for improvement. - * - * 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() takes two more parameters than PLUGIN_SET_INFO(), - * for a total of six parameters. - * - * - Localedir - * - Gettextpackage - * - Plugin name - * - Short description - * - Version - * - Author - * - * 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 + @endcode + + +Now you might like to look at Geany's source code for core plugins such as +@a plugins/demoplugin.c. + +@section furtherimprovements Furter Improvements and next steps +@subsection translatable_plugin_information Translatable plugin information + +After having written our first plugin, there is still room for improvement. + +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() takes two more parameters than PLUGIN_SET_INFO(), +for a total of six parameters. + + - Localedir + - Gettextpackage + - Plugin name + - Short description + - Version + - Author + +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 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 how this is done in the above example. - * - * 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 - * +@endcode

- * 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 +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 how this is done in the above example. + +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 + + +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) { main_locale_init(LOCALEDIR, GETTEXT_PACKAGE); @@ -467,9 +466,10 @@ void plugin_init(GeanyData *data) g_signal_connect(main_menu_item, "activate", G_CALLBACK(item_activate_cb), NULL); } - * @endcode - * - * @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. - **/ +@endcode + +@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 E-Mail was brought to you by github_commit_mail.py (Source: https://github.com/geany/infrastructure).