From: Paul L. <pa...@sq...> - 2008-07-23 06:12:10
|
> - url="http://squirrelmail.org/docs/devel-doc/squirrelmail/_functions_global_php.html#functionsqgetGlobalVar" > + url="http://squirrelmail.org/docs/devel-code/squirrelmail/_functions_global_php.html#functionsqgetGlobalVar" You still missed some like this one. |
From: Fredrik J. <jer...@sq...> - 2008-07-23 06:22:58
|
>> - >> url="http://squirrelmail.org/docs/devel-doc/squirrelmail/_functions_glo >> bal_php.html#functionsqgetGlobalVar" + >> url="http://squirrelmail.org/docs/devel-code/squirrelmail/_functions_gl >> obal_php.html#functionsqgetGlobalVar" > > You still missed some like this one. It sucks to be me. ;) Thanks for pointing it out. I've committed once again. Sincerely, Fredrik |
From: <jer...@us...> - 2008-07-23 06:21:08
|
Revision: 13251 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13251&view=rev Author: jervfors Date: 2008-07-23 06:21:04 +0000 (Wed, 23 Jul 2008) Log Message: ----------- Updating the links to the source code documentation. Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2008-07-23 05:59:38 UTC (rev 13250) +++ trunk/documentation/devel/devel.sgml 2008-07-23 06:21:04 UTC (rev 13251) @@ -337,9 +337,9 @@ <itemize> <item><tt/sqGetGlobalVar()/ (<url - url="http://squirrelmail.org/docs/stable-code/squirrelmail/_squirrelmail_functions_global_php.html#functionsqgetGlobalVar" + url="http://squirrelmail.org/docs/stable-code/squirrelmail/_functions---global.php.html#functionsqgetGlobalVar" name="stable"> and <url - url="http://squirrelmail.org/docs/devel-code/squirrelmail/_functions_global_php.html#functionsqgetGlobalVar" + url="http://squirrelmail.org/docs/devel-code/squirrelmail/_functions---global.php.html#functionsqgetGlobalVar" name="development">) <item><tt/sqsession_register()/ (<url url="http://squirrelmail.org/docs/stable-code/squirrelmail/_functions---global.php.html#functionsqsession_register" This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <pdo...@us...> - 2008-07-23 08:25:32
|
Revision: 13252 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13252&view=rev Author: pdontthink Date: 2008-07-23 08:25:26 +0000 (Wed, 23 Jul 2008) Log Message: ----------- Starting to rewrite and update plugin documentation, but there is so much left to do... Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2008-07-23 06:21:04 UTC (rev 13251) +++ trunk/documentation/devel/devel.sgml 2008-07-23 08:25:26 UTC (rev 13252) @@ -680,7 +680,7 @@ <sect1>The base URI funcion <p> -TODO: Add information about the base URI funcion. +FIXME: Add information about the base URI funcion. <sect1>Version numbering <sect2>The version number format<label id="versionformat"> @@ -1140,40 +1140,64 @@ use <tt>htmlspecialchars()</tt> twince on the same string, since that might break the decoded string. -<sect>Developing plugins +<sect>Developing plugins<label id="developing_plugins"> <p> -Due to the large number and wide range of functions plugins can cover it is -impractical to add all but the most popular to the SquirrelMail core project. -There is a separate <url url="http://sourceforge.net/projects/sm-plugins/" -name="SM Plugins"> project registered at SourceForge to house plugin code, -developers should consider joining this project. +SquirrelMail is built with an ingenious and powerful system that allows +add-ons known as plugins to extend its feature set in almost infinite +directions. This is one of the main reasons cited when users and +administrators explain SquirrelMail as their webmail of choice, and the +technology behind it has also been borrowed for other projects. -In addition to this document, help writing plugins is easily obtained by posting -to the <url url="http://squirrelmail.org/docs/admin/admin-12.html#mailinglists" -name="SquirrelMail plugins mailing list">. +It is also thanks to the many plugin authors that have contributed large +amounts of code and a wide array of functionality ideas that SquirrelMail +is as popular as it is. The SquirrelMail team would like to encourage +authors to contribute in the best way possible, which is what the following +information will enable them to do. If you are considering adding a feature +to SquirrelMail, this is the best place to start. -<sect1>The plugin architecture +<sect1>Before embarking<label id="before_developing_plugins"> <p> +One of the most fun parts about programming is seeing an idea turn into a +working product - the transition from "what if SquirrelMail could do..." +to "SquirrelMail CAN do...." The SquirrelMail team can appreciate and +relate to that kind of enthusiasm, but we also don't want to see it go to +waste. Therefore, the first thing to be done before considering the development +of a new plugin (for public consumption at least) is to ask the SquirrelMail +team if anyone has already attempted to implement the idea. It is also +extremely helpful to announce your intentions in public so that the +SquirrelMail community can provide feedback and help refine the idea BEFORE +it is implemented. + +Additionally, in keeping with the SquirrelMail theme of providing a product +that is simple to install and maintain, the team's philosophy regarding +plugins is to avoid the "Firefox syndrome", wherein it can take hours for +an administrator to understand what plugin is the right one for them. +Plugins that contain similar feature sets should be merged and authors should +work collaboratively instead of duplicating each others' efforts. If there +is a plugin on the SquirrelMail web site that <it/almost/ does what you +want to do, please inquire with its author and/or the SquirrelMail team +about enhancing it with your ideas. + +<sect1>The plugin architecture<label id="plugin_architecture"> +<p> The plugin architecture of SquirrelMail is designed to make it possible to add new features without having to patch SquirrelMail itself. Functionality like -password changing, displaying ads and calendars should be possible to add as -plugins. +changing user passowrds, displaying ads and calendars should be possible to add +as plugins. In this scheme, either package (SquirrelMail or a plugin) may be +upgraded independently without risk of one breaking the other. <sect2>The idea <p> -The idea is to be able to run random code at given places in the SquirrelMail -code. This random code should then be able to do whatever needed to enhance the -functionality of SquirrelMail. The places where code can be executed are called -"hooks". +The idea is to be able to run random (plugin) code at given places in the +SquirrelMail core. This random code should then be able to do whatever is +needed to enhance the functionality of SquirrelMail. The places where plugin +code can be executed are called "hooks". -There are some limitations in what these hooks can do. It is difficult to use +There are some limitations with what these hooks can do. It is difficult to use them to change the layout and to change functionality that already is in SquirrelMail. -Some way for the plugins to interact with the help subsystem and translations -will be provided. - -<sect2>The implementation +<sect2>The implementation<label id="plugin_implementation"> <p> The plugin start point in the main SquirrelMail code is in the file <tt>functions/plugin.php</tt>. In places where hooks are made available, they @@ -1188,336 +1212,237 @@ name of the subdirectory is considered to be the name of the plugin. Note that the plugin will not function correctly if this is not the case. -To start using a plugin, its name must be added to the <tt/$plugins/ array in -<tt/config.php/ like this: +A plugin is registered with SquirrelMail by using the configuration utility +or by manually editing the SquirrelMail configuration file. When adding a +plugin manually, its name (its directory name) must be added to the +<tt/$plugins/ array in <tt/config.php/ like this: <tscreen><verb> $plugins[] = 'plugin_name'; </verb></tscreen> -When a plugin is registered, the file <tt>plugins/plugin_name/setup.php</tt> is -included and the function <tt/squirrelmail_plugin_init_plugin_name()/ is called -with no parameters. That function is where the plugin may register itself -against any hooks it wishes to take advantage of. +<label id="plugin_registration">When a plugin is registered, the file +<tt>plugins/plugin_name/setup.php</tt> is loaded and the function +<tt/squirrelmail_plugin_init_<plugin_name>()/ is called with no parameters. +That function is where the plugin may register itself against any hooks it +wishes to take advantage of. +As of SquirrelMail 1.5.2, the <tt>plugins/plugin_name/setup.php</tt> file is +parsed at <it/configuration/ time instead of at run time as a performance +enhancement. The resultant <tt/$squirrelmail_plugin_hooks['hookname']/ array +is then stored statically in the SquirrelMail <tt/config/ directory in a file +called <tt/plugin_hooks.php/. Plugin authors should keep in mind that when +making changes to the hook structure of their plugins, they will need to +re-run the SquirrelMail configuraion utility or manually edit +<tt/plugin_hooks.php/ before the changes will take effect. + <sect1>The starting point -<sect2>Plugin initialization +<sect2>Plugin initialization<label id="plugin_setup_file"> <p> All plugins must contain a file called <tt/setup.php/ and must include a function called <tt/squirrelmail_plugin_init_<plugin_name>()/ therein. -Since including numerous plugins can slow SquirrelMail's performance down +Since including numerous plugins can slow SquirrelMail's performance considerably, the <tt/setup.php/ file should contain little else. Any functions that are registered against plugin hooks should do little more than call another -function in a different file. +function in a different file. No other files should be included in the global +scope of <tt/setup.php/, as this defeats the purpose of keeping it streamlined. Any other files used by the plugin should also be placed in the plugin directory -(or subdirectory thereof) and should contain the bulk of the plugin logic. +(or a subdirectory thereof) and should contain the bulk of the plugin logic. The function <tt/squirrelmail_plugin_init_<plugin_name>()/ is called to -initalize a plugin. This function could look something like this (if the plugin -was named "demo" and resided in the directory <tt>plugins/demo/</tt>): +initalize a plugin as explained <ref id="plugin_registration" name="above">. This +function could look something like this (if the plugin was named "demo" and +resided in the directory <tt>plugins/demo/</tt>): -<tscreen><verb> +<label id="plugin_init_example"><tscreen><verb> +/** + * Register this plugin with SquirrelMail + * + */ function squirrelmail_plugin_init_demo() { global $squirrelmail_plugin_hooks; - $squirrelmail_plugin_hooks['generic_header']['demo'] = 'plugin_demo_header'; - $squirrelmail_plugin_hooks['menuline']['demo'] = 'plugin_demo_menuline'; + $squirrelmail_plugin_hooks['optpage_register_block']['demo'] + = 'plugin_demo_options'; + $squirrelmail_plugin_hooks['login_cookie']['demo'] + = 'plugin_demo_login'; } </verb></tscreen> -Please note that as of SquirrelMail 1.5.2, this function is no longer -called at run time and is instead called (actually, just parsed) only -once at configuration time. Thus, the inclusion of any dynamic code -(anything except hook registration) here is strongly discouraged. +Again, please note that as of SquirrelMail 1.5.2, this function is no longer +called at run time and is instead called (actually, it is only parsed, never +executed) only once at configuration time. Thus, the inclusion of any dynamic +code (anything except hook registration) here is strongly discouraged. <sect2>Adding functionality <p> -In this example, the "demo" plugin should also have two other functions in its -<tt/setup.php/ file called <tt/plugin_demo_header()/ and -<tt/plugin_demo_menuline()/. The first of these might look something like this: +In the example <ref id="plugin_init_example" name="above">, the "demo" plugin +should also have two other functions in its <tt/setup.php/ file called +<tt/plugin_demo_options()/ and <tt/plugin_demo_login()/. The first of these +might look something like this: <tscreen><verb> -function plugin_demo_header() { - include_once(SM_PATH . 'plugins/demo/functions.php'); - plugin_demo_header_do(); -} -</verb></tscreen> - -The function called <tt/plugin_demo_header_do()/ in the file -<tt>plugins/demo/functions.php</tt> contains the plugin's core logic for the -<tt/generic_header/ hook. - -<sect1>Versioning -<sect2>Version numbering -<p> -In order to facilitate easier (and possibly automated) plugin management by -system administrators as well as in-SquirrelMail functionality that enables -cross-plugin compatibility and communication, plugin versioning should remain -consistent with that of SquirrelMail itself. While SquirrelMail does its -best to work with non-standard version strings, versioning such as that -explained in <ref id="versionformat" name="Version numbering">, with the -possible addition of an applicable SquirrelMail version, is the best way -to track your plugin's development (i.e., "1.0.4-1.4.5" or just "1.0.4"). -Versions with only two digits ("1.0-1.4.5" or just "1.0") are also acceptable -(a third digit of zero is implied). - -<sect2>Version reporting -<p> -The way any automated process gets its hands on the plugin version string -depends on the SquirrelMail version being used. As of SqruirrelMail 1.5.2, -plugins should include an administrative function in <tt/setup.php/ that -returns an array of details that describe the plugin, including its version -number. The function must be named <tt/<plugin name>_info()/ and -should return an associative array of version and requirements information. -Currently, at least the following elements are required, but the more -information returned, the better. - -<itemize> - <item>plugin name - <item>plugin version - <item>minimum SquirrelMail - <item>version - <item>summary - <item>details - <item>requires_configuration - <item>requires_source_patch -</itemize> - -Depending on the plugin, other information such as required PHP extensions -or Pear packages should be included. Currently, SquirrelMail understands -the following values: - -<tscreen><verb> -array( - 'english_name' => 'My Plugin Name', // different than directory name - 'version' => '1.0.0', - 'required_sm_version' => '1.5.2', - 'summary' => 'This is the short plugin description', - 'details' => 'This is the long, detailed plugin description', - 'requires_configuration' => 1, // can be 0 if no config file required - 'requires_source_patch' => 0, // set to 2 if depends on SM version - 'required_plugins' => array( // plugin name and version sub-array - 'compatibility' => '2.0.3', - ), - 'required_php_modules' => array( - 'recode' - ), - 'required_pear_packages' => array( - 'Cache_Lite', - 'MDB2', - ), - 'required_functions' => array( - 'recode_string', - ), - 'required_php_version' => '4.1.0', - 'other_requirements' => 'Courier Maildrop LDA', - 'external_project_uri' => 'http://example.org/my_plugin' -); -</verb></tscreen> - -The more of these that are returned to SquirrelMail, the more useful -and cooperative a plugin will be. - -TODO: might be nice to see something like this for templates too (version/language(HTML,XML,XHTML,CHTML,WML,etc)/engine(Smarty,PHP,etc)/intended interface... - -Prior to SquirrelMail 1.5.2, a function called <tt/<plugin name>_version()/ -was required. For the sake of compatibility, it can be piggy-backed on top of -the <tt/<plugin name>_info()/ function, such that <tt/setup.php/ looks like: - -<tscreen><verb> /** - * Returns info about this plugin + * Add link to the Demo options page on the SquirrelMail + * main options page listing * */ -function demo_info() -{ - - return array( - 'english_name' => 'Favorite Colors Demo', - 'version' => '1.0', - 'required_sm_version' => '1.4.0', - 'summary' => 'Shows user\'s favorite color in folder list.', - 'details' => 'This plugin will show the user\'s favorite color above the folder list.', - 'requires_configuration' => 0, - 'requires_source_patch' => 0, - ); - +function plugin_demo_options() { + include_once(SM_PATH . 'plugins/demo/functions.php'); + plugin_demo_options_do(); } - - -/** - * Returns version info about this plugin - * - */ -function demo_version() -{ - - $info = demo_info(); - return $info['version']; - -} </verb></tscreen> -There is also a legacy version reporting mechanism that we would like plugin -authors to implement, since we are still in a transition period between the -older and newer reporting usages. The now deprecated reporting mechanism is to -create a file called <tt/version/ in the plugin directory. That file should -have only two lines: the first line should have the name of the plugin as -named on the SquirrelMail web site (this is often a prettified version of the plugin -directory name), and the second line must have the version and nothing more. So -for our "demo" plugin, whose name on the web site might be something like "Demo -Favorite Colors", the file <tt>plugins/demo/version</tt> should have these two -lines: +The function called <tt/plugin_demo_options_do()/ in the file +<tt>plugins/demo/functions.php</tt> contains the plugin's core logic for the +<tt/optpage_register_block/ hook. Aside from <tt/plugin_demo_options()/ and +<tt/plugin_demo_login()/ and the +<ref id="plugin_version_reporting" name="version reporting information explained below">, +there should be little-to-nothing else in <tt/setup.php/. -<tscreen><verb> -Favorite Colors Demo -1.0 -</verb></tscreen> - -<sect1>Configuration +<sect1>Hooks <p> -It is common to need a configuration file that holds some variables that are set -up at install time. For ease of installation and maintenance, you should place -all behavioral settings in a config file, isolated from the rest of your plugin -code. A typical file name to use is <tt/config.php/. If you are using such a -file, you should <it/not/ include a file called <tt/config.php/ in your plugin -distribution, but instead a copy of that file called <tt/config.sample.php/. -This helps systems administrators avoid overwriting the <tt/config.php/ files -and losing all of their setup information when they upgrade your plugin. +In the example <ref id="plugin_init_example" name="above">, the "demo" plugin +uses two "hooks" called "optpage_register_block" and "login_cookie". Which +hooks a plugin uses depends on what kind of functionality is being +implemented - where in the SquirrelMail source code does the plugin need to +execute its own code? -<sect1>Security considerations -<sect2>Calling external programs -<p> -All plugin authors should consider the security implications of their plugin. -Great care must always be taken if the plugin calls external programs, especially -ones that require set-uid permissions. +Hooks themselves are functions executed by the SquirrelMail core using one of +just a few hook types which in turn pass execution to the plugins that have +registered themselves against the current hook as explained +<ref id="plugin_implementation" name="above">. -FIXME: more here about how to secure exec() calls with escapeshellarg() and named pipes method vs exec() +When executed, hooks are called with differing parameters and may or may not +take return values, all depending on the type of hook being called and the +context in which it is being used. On the source side (where the hook call +originates), all hooks have at least one parameter, which is the name of the +hook. After that, things get complicated (sometimes). - -<sect2>Storing sensitive data +<sect2>Hook types, parameters and return values <p> -If a plugin needs to store sensitive user configuration files or other such data, -please consider extra steps to secure such files. One very easy way to do so is -to wrap all configuration files in PHP tags (and C-style block comments if the -configuration data is not PHP code itself): +The design of each of the hook types has changed somewhat starting with +SquirrelMail version 1.5.2, so we provide a description of the hook types for +both the 1.4 release series and versions starting with 1.5.2. Despite the +differences noted here, in most cases, plugins will run on the same hook +without the need for version-specific code in either environment (however, +there are other differences that do require version-specific code, which are +explained elsewhere). -<tscreen><verb> -<?php /* +<descrip> -# below is example non-PHP configuration -# data that is secured from prying eyes +<tag>SquirrelMail 1.5.2+ uses three hook functions: <tt/do_hook()/, +<tt/concat_hook_function()/, and <tt/boolean_hook_function()/.</tag> -username_1 = admin -username_2 = super_admin +The <tt/do_hook()/ function is the most common do-all hook in the SquirrelMail +core. It provides all plugins a single parameter which is passed through the +hook by reference, so, if a plugin also accepts it by reference, it can be +changed as needed (and it is often an array of multiple values of interest to +plugins using a particular hook: take a look in the core - the second argument +to the <tt/do_hook/ call is what is passed along to the plugins). There is a +second parameter given to plugins, but it is not normally used: it is the +current value of the ultimate hook return value. All plugins are responsible +for sharing the creation/modification of whatever <tt/do_hook/ returns. The +ultimate return value is whatever the <it/last/ plugin returns from its hook +implementation, but if it does return something, it should be contious of +checking if there was already a return value created by other plugins, which +is what is given as the second parameter to the plugin. As with all hooks, +the usage of the hook parameters and/or its return value are determined based +on the context in which the hook is used - you have to look at it in the +SquirrelMail core. Please remember NEVER to output any HTML directly during +hook execution. -*/ ?> -</verb></tscreen> +Read more about the <tt/do_hook()/ function in the +<url url="http://squirrelmail.org/docs/devel-code/squirrelmail/_functions---plugin.php.html#functiondo_hook" name="1.5 API documentation">. -Another approach is to store sensitive configuration data in SquirrelMail's -own <tt/$data/ directory, since most system administrators (at least those who -have read the installation instructions) know that the <tt/$data/ directory -needs to be protected and (hopefully) have made sure that it has been. +The <tt/concat_hook_function()/ is used in places where the SquirrelMail +core needs to aggregate return data from all plugins on the same hook. +Plugins are provided with the same (modifyable) parameter as with <tt/do_hook/. +In some places, the core will expect all plugins to return strings, which will +be concatenated together and returned to the SquirrelMail core. In other cases, +arbitrary values are used by the core, which will be placed into an array of +return values. What kind of return value is expected is best determined by +inspecting the core where the hook is called. Please remember NEVER to output +any HTML directly during hook execution. -Never store unsecured configuration data that contains any user or system-specific -information in your plugin directory. Even the above suggestions -may not be sufficient depending on how sensitive the data is that you are -storing. In such a situation, you might think about a more complex encryption -scheme such as the one provided by the <bf/vadmin/ plugin. +Read more about the <tt/concat_hook_function()/ function in the +<url url="http://squirrelmail.org/docs/devel-code/squirrelmail/_functions---plugin.php.html#functionconcat_hook_function" name="1.5 API documentation">. -Note that just shipping unsecured configuration files along with a -configuration file for Apache (<tt/.htaccess/) is not sufficient because -not every system uses Apache as its web server. +The <tt/boolean_hook_function()/ allows plugins to vote for a specified action. +What that action is is entirely dependent on how the hook is used in the +SquirrelMail core (look for yourself). Plugins make their vote by returning a +boolean <tt/TRUE/ or <tt/FALSE/ value. This hook may be configured to tally +votes in one of three ways. This configuration is done with the third parameter +in the hook call in the core: -<sect2>Disallowing access for diabled plugins -<p> +<itemize> + <item>> 0 -- At least one <tt/TRUE/ will override all <tt/FALSE/. + <item>< 0 -- At least one <tt/FALSE/ will override all <tt/TRUE/. + <item>= 0 -- Majority wins. Any ties are broken with the last parameter in the + hook call. +</itemize> -In some cases, it is also prudent to make sure that the plugin doesn't perform -its function when it is not enabled. Any functions or files that contain PHP -code that is <tt/not/ wrapped inside a function can be protected from being -executed when the plugin is not activated by adding code similar to this: +Plugins using <tt/boolean_hook_function/ are provided with the same +(modifyable) parameter as with <tt/do_hook/. Please remember NEVER to output +any HTML directly during hook execution. -<tscreen><verb> -if ( !is_plugin_enabled('my_plugin_name') ) { - exit('The plugin my_plugin_name isn't enabled in the SquirrelMail configuration.'); -} -</verb></tscreen> +Read more about the <tt/boolean_hook_function()/ function in the +<url url="http://squirrelmail.org/docs/devel-code/squirrelmail/_functions---plugin.php.html#functionboolean_hook_function" name="1.5 API documentation">. -Note, however, that sometimes <tt/other/ plugins can legitimately access a -disabled plugin, so don't shoot yourself in the foot with too much protection. +<tag>SquirrelMail 1.4 uses four hook functions: <tt/do_hook()/, <tt/do_hook_function()/, +<tt/concat_hook_function()/, and <tt/boolean_hook_function()/.</tag> - -<sect1>Hooks -<p> -Hooks, when executed, are called with differing parameters and may or may not -take return values, all depending on the type of hook being called and the -context in which it is being used. On the source side (where the hook call -originates), all hooks have at least one parameter, which is the name of the -hook. After that, things get complicated. - -<sect2>Hook types: parameters and return values -<p> -SquirrelMail uses four hook functions: <tt/do_hook()/, <tt/do_hook_function()/, -<tt/concat_hook_function()/, and <tt/boolean_hook_function()/. - -The <tt/do_hook()/ function is a simple function that allows injecting custom -HTML or override default interface data. It doesn't pass any data and doesn't -ask for anything back. A limited number of <tt/do_hook()/ calls do pass some -extra parameters, in which case your plugin may modify the given data if you do -so by reference. It is not necessary to return anything from your function in -such a case; modifying the parameter data by reference is what does the job -(although the hook call itself (in the source) must grab the return value for -this to work). Note that in this case, the parameter to your hook function will -be an array, the first element simply being the hook name, followed by any other -parameters that may have been included in the actual hook call in the source. +The <tt/do_hook()/ function is a simple function that allows injecting of +custom output or override of default interface data. It doesn't pass any +data and doesn't ask for anything back. A limited number of <tt/do_hook()/ +calls do pass some extra parameters, in which case your plugin may modify +the given data if you do so by reference. It is not necessary to return +anything from your function in such a case; modifying the parameter data +by reference is what does the job (although the hook call itself (in the +SquirrelMail core) must grab the return value for this to work). Note that +in this case, the one and only parameter to your hook function will be an +array, the first element simply being the hook name, followed by any other +parameters that may have been included in the actual hook call in the core. Modify parameters with care! -Read more about the <tt/do_hook()/ function in the <url -url="http://squirrelmail.org/docs/stable-code/squirrelmail/_functions---plugin.php.html#functiondo_hook" -name="stable"> and <url -url="http://squirrelmail.org/docs/devel-code/squirrelmail/_functions---plugin.php.html#functiondo_hook" -name="development"> API documentation. +Read more about the <tt/do_hook()/ function in the +<url url="http://squirrelmail.org/docs/stable-code/squirrelmail/_functions---plugin.php.html#functiondo_hook" name="1.4 API documentation"> The <tt/do_hook_function()/ was intended to be the main hook type used when the source needs to get something back from your plugin. It is somewhat limited in that it will only use the value returned from the <it/last/ plugin registered -against the hook. The source for this hook might use the return value for -internal purposes, or might expect you to provide text or HTML to be sent to the -client browser (you'll have to look at its use in context to understand how you -should return values here). The parameters that your hook function gets will be -anything you see <it/after/ the hook name in the actual hook call in the source. -These cannot be changed in the same way that the <tt/do_hook()/ parameters can -be. +against the hook. The SquirrelMail core might use the return value for this hook +type for internal purposes, or might expect you to provide text or HTML to be +sent to the client browser (you'll have to look at its use in context to +understand how you should return values here). The parameters that your hook +function gets will be anything you see <it/after/ the hook name in the actual +hook call in the source. These cannot be changed in the same way that the +<tt/do_hook()/ parameters can be. -Read more about the <tt/do_hook_function()/ function in the <url -url="http://squirrelmail.org/docs/stable-code/squirrelmail/_functions---plugin.php.html#functiondo_hook_function" -name="stable"> and <url -url="http://squirrelmail.org/docs/devel-code/squirrelmail/_functions---plugin.php.html#functiondo_hook_function" -name="development"> API documentation. +Read more about the <tt/do_hook_function()/ function in the +<url url="http://squirrelmail.org/docs/stable-code/squirrelmail/_functions---plugin.php.html#functiondo_hook_function" name="1.4 API documentation"> The <tt/concat_hook_function()/ fixes some shortcomings of the -<tt/do_hook_function()/. It uses the return values of all plugins registered -against the hook. In order to do so, the return value is assumed to be a string, -which is just piled on top of whatever it got from the other plugins working on -the same hook. Again, you'll have to inspect the source code to see how such -data is put to use, but most of the time, it is used to create a string of HTML -to be inserted into the output page. The parameters that your hook function will -get are the same as for the <tt/do_hook_function/; they are anything <it/after/ -the hook name in the actual hook call in the source. +<tt/do_hook_function()/ in that it uses the return values of all plugins +registered against the hook. In order to do so, the return value is assumed to +be a string, which is just piled (concatenated) on top of whatever it got from +the other plugins working on the same hook. Again, you'll have to inspect the +source code to see how such data is put to use, but most of the time, it is +used to create a string of HTML to be inserted into the output page. The +parameters that your hook function will get are the same as for the +<tt/do_hook_function/; they are anything <it/after/ the hook name in the +actual hook call in the source. -Read more about the <tt/concat_hook_function()/ function in the <url -url="http://squirrelmail.org/docs/stable-code/squirrelmail/_functions---plugin.php.html#functionconcat_hook_function" -name="stable"> and <url -url="http://squirrelmail.org/docs/devel-code/squirrelmail/_functions---plugin.php.html#functionconcat_hook_function" -name="development"> API documentation. +Read more about the <tt/concat_hook_function()/ function in the +<url url="http://squirrelmail.org/docs/stable-code/squirrelmail/_functions---plugin.php.html#functionconcat_hook_function" name="1.4 API documentation"> The <tt/boolean_hook_function()/ allows plugins to vote for a specified action. -What that action is is entirely dependent on how the hook is used in the source -(look for yourself). Plugins make their vote by returning a boolean <tt/TRUE/ or -<tt/FALSE/ values. This hook may be configured to tally votes in one of three -ways. This configuration is done with the third parameter in the hook call in -the source: +What that action is is entirely dependent on how the hook is used in the +SquirrelMail core (look for yourself). Plugins make their vote by returning a +boolean <tt/TRUE/ or <tt/FALSE/ value. This hook may be configured to tally +votes in one of three ways. This configuration is done with the third parameter +in the hook call in the core: <itemize> <item>> 0 -- At least one <tt/TRUE/ will override all <tt/FALSE/. @@ -1526,16 +1451,15 @@ hook call. </itemize> -The plugin's hook function will get the second paramter in the hook call in the -source as its parameter (this might be an array if multiple values need to be -passed). +Each plugin registered on such a hook will receive the second paramter in the +hook call in the core as its one and only parameter (this might be an array if +multiple values need to be passed). -Read more about the <tt/boolean_hook_function()/ function in the <url -url="http://squirrelmail.org/docs/stable-code/squirrelmail/_functions---plugin.php.html#functionboolean_hook_function" -name="stable"> and <url -url="http://squirrelmail.org/docs/devel-code/squirrelmail/_functions---plugin.php.html#functionboolean_hook_function" -name="development"> API documentation. +Read more about the <tt/boolean_hook_function()/ function in the +<url url="http://squirrelmail.org/docs/stable-code/squirrelmail/_functions---plugin.php.html#functionboolean_hook_function" name="1.4 API documentation"> +</descrip> + <sect2>List of hooks <p> This is a list of all hooks currently available in SquirrelMail, ordered by @@ -2041,6 +1965,7 @@ <item><tt><bf/SMOPT_TYPE_HIDDEN/</tt> for a hidden input (not actually shown on preferences page). <item><tt><bf/SMOPT_TYPE_COMMENT/</tt> for a showing the text specified by the <tt/comment/ attribute, but no user input is needed. <item><tt><bf/SMOPT_TYPE_FLDRLIST/</tt> for a select list of IMAP folders. + <item><tt><bf/SMOPT_TYPE_FLDRLIST_MULTI/</tt> for a select list of IMAP folders where the user can select more than one folder. </itemize> <tag><tt/refresh/ (optional)</tag> @@ -2332,6 +2257,247 @@ TODO: Possibly provide link to the include hierarchy provided by init.php/validate.php +<sect1>Configuration<label id="plugin_configuration"> +<p> +It is common to need a configuration file that holds some variables that are +set up at install time. For ease of installation, maintenance and upgrades, all +behavioral settings should be placed in a configuration file that is isolated +from the rest of the plugin code. A typical file name to use is +<tt/config.php/. The plugin should allow the administrator to store this file +in either the plugin directory or in the main SquirrelMail configuration +directory, giving precedence to the latter. + +Plugins that make use of configuration files should <it/not/ include a file +called <tt/config.php/ in distribution packages; instead, a copy of that file +named <tt/config.sample.php/ is desirable, since customized <tt/config.php/ +files will not be lost upon upgrading the plugin. + +A plugin can try to be smart about where to find the needed configuration +file by doing something such as this: + +<tscreen><verb> +if (!@include_once(SM_PATH . 'config/config_demo.php')) + if (!@include_once(SM_PATH . 'plugins/demo/config.php')) + @include_once(SM_PATH . 'plugins/demo/config.sample.php'); +</verb></tscreen> + +This assumes that the plugin has some sensible defaults in the sample +configuration file - if the plugin <it/must/ be configured specifically +for the system upon which it is installed, remove the third line in this +example. + +<sect1>Versioning +<sect2>Version numbering +<p> +In order to facilitate easier (and possibly automated) plugin management by +system administrators as well as in-SquirrelMail functionality that enables +cross-plugin compatibility and communication, plugin versioning should remain +consistent with that of SquirrelMail itself. While SquirrelMail does its +best to work with non-standard version strings, versioning such as that +explained in <ref id="versionformat" name="Version numbering">, with the +possible addition of an applicable SquirrelMail version, is the best way +to track your plugin's development (i.e., "1.0.4-1.4.5" or just "1.0.4"). +Versions with only two digits ("1.0-1.4.5" or just "1.0") are also acceptable +(a third digit of zero is implied). + +<sect2>Version reporting<label id="plugin_version_reporting"> +<p> +The way any automated process gets its hands on the plugin version string +depends on the SquirrelMail version being used. As of SquirrelMail 1.5.2, +plugins should include an administrative function in <tt/setup.php/ that +returns an array of details that describe the plugin, including its version +number. The function must be named <tt/<plugin name>_info()/ and +should return an associative array of version and requirements information. +Currently, at least the following elements are required, but the more +information returned, the better. + +<tabular ca="lll"> +<bf/Element Name/|<bf/Explanation/|<bf/Example Values & Notes/@ +<tt/english_name/|Prettified plugin display name|"Demo Future Prediction" (can be different than the plugin's directory name)@ +<tt/version/|Plugin version|"1.0", "2.5.1", etc.@ +<tt/authors/|Plugin authors|An array of authors, where each author is described by a sub-array that is keyed by "email" and "sm_site_username" (the latter to be used at a later date). See below for an example.@ +<tt/required_sm_version/|Minimum required SquirrelMail version|"1.2.8", "1.4.15", "1.5.2", etc.@ +<tt/summary/|Functionality summary|This should be a brief sentence or two at the most.@ +<tt/details/|Functionality details|This can be much more verbose compared to the <tt/summary/.@ +<tt/requires_configuration/|Whether or not the plugin requires a configuration file to be prepared by the administrator|boolean <tt/0/ or <tt/1/.@ +<tt/requires_source_patch/|Whether or not the plugin requires patching of the SquirrelMail source code|boolean <tt/0/ or <tt/1/ (or <tt/2/ to indicate that patching is optional (enables optional functionality) or is only required for some SquirrelMail versions, although the latter should be done in more detail using <tt/per_version_requirements/).@ +</tabular> + +Other optional elements include: + +<tabular ca="lll"> +<bf/Element Name/|<bf/Explanation/|<bf/Example Values & Notes/@ +<tt/required_php_version/|Minimum required PHP version|"4.1.0", "4.4.8", "5.2.6", etc.@ +<tt/required_php_modules/|List of required PHP extensions|An array of PHP extension names needed by the plugin: <tt/array("recode", "gd", )/@ +<tt/required_functions/|List of required PHP functions|An array of function names needed by the plugin: <tt/array("recode_string", "ngettext", )/@ +<tt/required_pear_packages/|List of required Pear packages|An array of Pear package names needed by the plugin: <tt/array("MDB2", "Cache_Lite", )/@ +<tt/required_plugins/|List of other plugins that are required|An array of required plugins, where each plugin is described by a sub-array that is keyed by "version" (the minimum version of the plugin that is required) and "activate" (whether or not the plugin needs to be activated, or merely present in the plugins directory (as a code library)). Instead of the sub-array, the special constant <tt/SQ_INCOMPATIBLE/ may be used to indicate that this plugin is not compatible with the other. See below for an example.@ +<tt/rpc/|List of RPC commands that this plugin answers to|A two-element array keyed by "commands" and "errors". Each of these contains a sub-array. The "commands" array is keyed by RPC command name, where corresponding values are the English explanations for what each command does. The "errors" array is keyed by each possible error number that the plugin's RPC interface might produce, where corresponding values are English explanations of what each error number means. <tt/array("commands" => array("demo_get_one_prediction" => "Peer into the crystal ball once"), "errors" => array(720 => "demo_get_one_prediction failed"),)/@ +<tt/other_requirements/|Some other non-SquirrelMail or non-PHP requirements|<tt/"Courier Maildrop LDA"/@ +<tt/external_project_uri/|Address of the project page or source code repository for the plugin|<tt>"http://example.org/my_plugin"</tt>@ +<tt/per_version_requirements/|List of requirements this plugin has that are different based on the SquirrelMail version being used|An array which is keyed by SquirrelMail version numbers. Any version numbers skipped receive the same requirements laid out for the last version number that is listed below the skipped one. Each value is then a sub-array that may contain any of the requirement entries listed here, such as <tt/requires_source_patch/, <tt/required_plugins/, etc., or a special constant called <tt/SQ_INCOMPATIBLE/ (set the associated value to boolean <tt/1/), which indicates that the plugin is not compatible with the corresponding version of SquirrelMail. <tt/SQ_INCOMPATIBLE/ may also replace the entire sub-array for the incompatible SquirrelMail version, which is easier to understand. See below for an example.@ +</tabular> + +A typical implementation of this function is as follows. Note that +this example shows a conditional requirement for the Compatibility +plugin that is due to the (required) use of <tt/sq_change_text_domain()/ +[FIXME: PROVIDE LINK FOR THE FOLLOWING] +(explained in the plugin internationalization section below), which +was added to the SquirrelMail core as of version 1.4.10 and 1.5.2. + +<tscreen><verb> +/** + * Returns info about this plugin + * + */ +function demo_info() +{ + + return array( + 'english_name' => 'Demo Future Prediction', + 'authors' => array( + 'Emma Goldman' => array( + 'email' => 'em...@st...', + 'sm_site_username' => 'emma', + ), + ), + 'summary' => 'Adds important information above the folder list.', + 'details' => 'This plugin automatically sees into the user\'s future and places important details about upcoming events above the folder list.', + 'version' => '2.5.1', + 'required_sm_version' => '1.2.9', + 'requires_configuration' => 0, + 'requires_source_patch' => 0, + 'per_version_requirements' => array( + '1.5.2' => array( + 'required_plugins' => array(), + ), + '1.5.0' => array( + 'required_plugins' => array( + 'compatibility' => array( + 'version' => '2.0.7', + 'activate' => FALSE, + ) + ) + ), + '1.4.10' => array( + 'required_plugins' => array(), + ), + '1.2.9' => array( + 'required_plugins' => array( + 'compatibility' => array( + 'version' => '2.0.7', + 'activate' => FALSE, + ) + ) + ), + ), + ); + +} +</verb></tscreen> + +Prior to SquirrelMail 1.5.2, a function called +<tt>/<plugin name>_version()</tt> was required. For the sake of +compatibility, it can be piggy-backed on top of the +<tt><plugin name>_info()</tt> function very simply as follows: + +<tscreen><verb> +/** + * Returns version info about this plugin + * + */ +function demo_version() +{ + $info = demo_info(); + return $info['version']; +} +</verb></tscreen> + +There is also a legacy version reporting mechanism that we would like plugin +authors to implement, since we are still in a transition period between the +older and newer reporting usages. The now deprecated reporting mechanism is to +create a file called <tt/version/ in the plugin directory. That file should +have only two lines: the first line should have the name of the plugin as +named on the SquirrelMail web site (this is often a prettified version of the plugin +directory name), and the second line must have the version and nothing more. So +for our "demo" plugin, whose name on the web site might be something like "Demo +Future Prediction", the file <tt>plugins/demo/version</tt> should have these two +lines: + +<tscreen><verb> +Demo Future Prediction +2.5.1 +</verb></tscreen> + +<sect1>Security considerations +<sect2>Calling external programs +<p> +All plugin authors should consider the security implications of their plugin. +Great care must always be taken if the plugin calls external programs, especially +ones that require set-uid permissions. + +FIXME: more here about how to secure exec() calls with escapeshellarg() and named pipes method vs exec() + + +<sect2>Storing sensitive data +<p> +If a plugin needs to store sensitive user configuration files or other such data, +please consider extra steps to secure such files. One very easy way to do so is +to wrap all configuration files in PHP tags (and C-style block comments if the +configuration data is not PHP code itself): + +<tscreen><verb> +<?php /* + +# below is example non-PHP configuration +# data that is secured from prying eyes + +username_1 = admin +username_2 = super_admin + +*/ ?> +</verb></tscreen> + +Another approach is to store sensitive configuration data in SquirrelMail's +own <tt/$data/ directory, since most system administrators (at least those who +have read the installation instructions) know that the <tt/$data/ directory +needs to be protected and (hopefully) have made sure that it has been. + +Never store unsecured configuration data that contains any user or system-specific +information in your plugin directory. Even the above suggestions +may not be sufficient depending on how sensitive the data is that you are +storing. In such a situation, you might think about a more complex encryption +scheme such as the one provided by the <bf/vadmin/ plugin. + +Note that just shipping unsecured configuration files along with a +configuration file for Apache (<tt/.htaccess/) is not sufficient because +not every system uses Apache as its web server. + +<sect2>Disallowing access for diabled plugins +<p> + +In some cases, it is also prudent to make sure that the plugin doesn't perform +its function when it is not enabled. Any functions or files that contain PHP +code that is <tt/not/ wrapped inside a function can be protected from being +executed when the plugin is not activated by adding code similar to this: + +<tscreen><verb> +if ( !is_plugin_enabled('my_plugin_name') ) { + exit('The plugin my_plugin_name isn't enabled in the SquirrelMail configuration.'); +} +</verb></tscreen> + +Note, however, that sometimes <tt/other/ plugins can legitimately access a +disabled plugin, so don't shoot yourself in the foot with too much protection. + +<sect1>Coding tips<label id="plugin_coding_tips"> +<p> +Listed below are several useful tips to keep in mind while coding plugins. Some of these items will be scrutinized and possibly treated as mandatory by the plugin team when evaluating new plugins. + +<sect2>Knowing what hook is running +<p> +Some plugins may register the same function against multiple hooks or otherwise run the same library code for more than one hook. If that code needs to make a hook-specific decision, it can look at the global variable called <tt/$currentHookName/. However, this variable is only available in SquirrelMail versions 1.5.1 and above, so it is more portable to use the function <tt/get_current_hook_name()/, which is provided by the Compatibility plugin (see elsewhere for more information about using the Compatibility plugin[FIXME: provide a link for this]). + <sect1>Compatibility with older versions of SquirrelMail <p> Whenever new versions of SquirrelMail are released, there is always a @@ -2435,6 +2601,22 @@ procedure above). </verb></tscreen> +<sect1>Storing code +<p> +[FIXME: expand this section] +Due to the large number and wide range of functions plugins can cover it is +impractical to add all but the most popular of these to the SquirrelMail +core project. +There is a separate <url url="http://sourceforge.net/projects/sm-plugins/" +name="SM Plugins"> project registered at SourceForge to house plugin code, +developers should consider joining this project. + +<sect1>Additional Resources +<p> +In addition to this document, help writing plugins is easily obtained by posting +to the <url url="http://www.squirrelmail.org/docs/admin/admin-12.html#ss12.3" +name="SquirrelMail plugins mailing list">. + <sect1>How to release your plugin <p> As long as you've consulted the list of plugin standards and done your best to @@ -2453,11 +2635,19 @@ tar -czvf demo-1.0-1.4.0.tar.gz demo </verb></tscreen> +<sect2>Requirements Checklist +<p> +Make sure the plugin meets the SquirrelMail plugin requirements explained throughout this document. Here is a quick checklist to help summarize the various requirements. + +<itemize> + <item>FIXME: WHERE SHOULD THIS CHECKLIST BE BEST PLACED IN THIS DOCUMENT? + <item>Keep <tt/setup.php/ <ref id="plugin_setup_file" name="small and efficient"> +</itemize> + +<sect2>Submitting the plugin +<p> When the plugin is ready to be reviewed by the SquirrelMail plugin team, mail it -to the SquirrelMail plugins team members. Also consider asking on the SquirrelMail -plugins mailing list for access to upload your plugin to the -<url url="http://squirrelmail.org/plugins.php" name="official third party plugin -list"> after your plugin is approved. +to the SquirrelMail plugins team members. When the plugin is approved and you're granted access to upload it, all you have to do is the actual uploading along with filling out some general information This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <pdo...@us...> - 2008-07-26 21:00:28
|
Revision: 13257 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13257&view=rev Author: pdontthink Date: 2008-07-26 21:00:25 +0000 (Sat, 26 Jul 2008) Log Message: ----------- Typos Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2008-07-24 18:16:44 UTC (rev 13256) +++ trunk/documentation/devel/devel.sgml 2008-07-26 21:00:25 UTC (rev 13257) @@ -2320,7 +2320,7 @@ <tt/summary/|Functionality summary|This should be a brief sentence or two at the most.@ <tt/details/|Functionality details|This can be much more verbose compared to the <tt/summary/.@ <tt/requires_configuration/|Whether or not the plugin requires a configuration file to be prepared by the administrator|boolean <tt/0/ or <tt/1/.@ -<tt/requires_source_patch/|Whether or not the plugin requires patching of the SquirrelMail source code|boolean <tt/0/ or <tt/1/ (or <tt/2/ to indicate that patching is optional (enables optional functionality) or is only required for some SquirrelMail versions, although the latter should be done in more detail using <tt/per_version_requirements/).@ +<tt/requires_source_patch/|Whether or not the plugin requires patching of the SquirrelMail source code|boolean <tt/0/ or <tt/1/ (or <tt/2/ to indicate that patching is optional (enables optional functionality) or is only required for some SquirrelMail versions, although the latter should be done in more detail using <tt/per_version_requirements/). </tabular> Other optional elements include: @@ -2335,7 +2335,7 @@ <tt/rpc/|List of RPC commands that this plugin answers to|A two-element array keyed by "commands" and "errors". Each of these contains a sub-array. The "commands" array is keyed by RPC command name, where corresponding values are the English explanations for what each command does. The "errors" array is keyed by each possible error number that the plugin's RPC interface might produce, where corresponding values are English explanations of what each error number means. <tt/array("commands" => array("demo_get_one_prediction" => "Peer into the crystal ball once"), "errors" => array(720 => "demo_get_one_prediction failed"),)/@ <tt/other_requirements/|Some other non-SquirrelMail or non-PHP requirements|<tt/"Courier Maildrop LDA"/@ <tt/external_project_uri/|Address of the project page or source code repository for the plugin|<tt>"http://example.org/my_plugin"</tt>@ -<tt/per_version_requirements/|List of requirements this plugin has that are different based on the SquirrelMail version being used|An array which is keyed by SquirrelMail version numbers. Any version numbers skipped receive the same requirements laid out for the last version number that is listed below the skipped one. Each value is then a sub-array that may contain any of the requirement entries listed here, such as <tt/requires_source_patch/, <tt/required_plugins/, etc., or a special constant called <tt/SQ_INCOMPATIBLE/ (set the associated value to boolean <tt/1/), which indicates that the plugin is not compatible with the corresponding version of SquirrelMail. <tt/SQ_INCOMPATIBLE/ may also replace the entire sub-array for the incompatible SquirrelMail version, which is easier to understand. See below for an example.@ +<tt/per_version_requirements/|List of requirements this plugin has that are different based on the SquirrelMail version being used|An array which is keyed by SquirrelMail version numbers. Any version numbers skipped receive the same requirements laid out for the last version number that is listed below the skipped one. Each value is then a sub-array that may contain any of the requirement entries listed here, such as <tt/requires_source_patch/, <tt/required_plugins/, etc., or a special constant called <tt/SQ_INCOMPATIBLE/ (set the associated value to boolean <tt/1/), which indicates that the plugin is not compatible with the corresponding version of SquirrelMail. <tt/SQ_INCOMPATIBLE/ may also replace the entire sub-array for the incompatible SquirrelMail version, which is easier to understand. See below for an example. </tabular> A typical implementation of this function is as follows. Note that @@ -2397,7 +2397,7 @@ </verb></tscreen> Prior to SquirrelMail 1.5.2, a function called -<tt>/<plugin name>_version()</tt> was required. For the sake of +<tt><plugin name>_version()</tt> was required. For the sake of compatibility, it can be piggy-backed on top of the <tt><plugin name>_info()</tt> function very simply as follows: This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <pdo...@us...> - 2008-08-17 00:26:50
|
Revision: 13263 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13263&view=rev Author: pdontthink Date: 2008-08-17 00:26:48 +0000 (Sun, 17 Aug 2008) Log Message: ----------- Change recommended example and default config file names/usage Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2008-08-16 08:58:58 UTC (rev 13262) +++ trunk/documentation/devel/devel.sgml 2008-08-17 00:26:48 UTC (rev 13263) @@ -2269,8 +2269,12 @@ Plugins that make use of configuration files should <it/not/ include a file called <tt/config.php/ in distribution packages; instead, a copy of that file -named <tt/config.sample.php/ is desirable, since customized <tt/config.php/ -files will not be lost upon upgrading the plugin. +named <tt/config_example.php/ is desirable, since customized <tt/config.php/ +files will not be lost upon upgrading the plugin. If the plugin does not need +environment-specific configuration settings, you may also consider including +a default configuration file so that the administrator does not need to +configure the plugin unless she wants to change some particular setting. +The usual default configuration file name is <tt/config_default.php/. A plugin can try to be smart about where to find the needed configuration file by doing something such as this: @@ -2278,13 +2282,11 @@ <tscreen><verb> if (!@include_once(SM_PATH . 'config/config_demo.php')) if (!@include_once(SM_PATH . 'plugins/demo/config.php')) - @include_once(SM_PATH . 'plugins/demo/config.sample.php'); + @include_once(SM_PATH . 'plugins/demo/config_default.php'); </verb></tscreen> -This assumes that the plugin has some sensible defaults in the sample -configuration file - if the plugin <it/must/ be configured specifically -for the system upon which it is installed, remove the third line in this -example. +If the plugin <it/must/ be configured specifically for the system upon which +it is installed, remove the third line in this example. <sect1>Versioning <sect2>Version numbering This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <pdo...@us...> - 2008-09-23 07:56:50
|
Revision: 13282 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13282&view=rev Author: pdontthink Date: 2008-09-23 07:56:40 +0000 (Tue, 23 Sep 2008) Log Message: ----------- Very minor change in wording Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2008-09-23 01:12:29 UTC (rev 13281) +++ trunk/documentation/devel/devel.sgml 2008-09-23 07:56:40 UTC (rev 13282) @@ -1345,13 +1345,12 @@ current value of the ultimate hook return value. All plugins are responsible for sharing the creation/modification of whatever <tt/do_hook/ returns. The ultimate return value is whatever the <it/last/ plugin returns from its hook -implementation, but if it does return something, it should be contious of -checking if there was already a return value created by other plugins, which -is what is given as the second parameter to the plugin. As with all hooks, -the usage of the hook parameters and/or its return value are determined based -on the context in which the hook is used - you have to look at it in the -SquirrelMail core. Please remember NEVER to output any HTML directly during -hook execution. +implementation, but if it does return something, it should be sure to check +if there was already a return value created by other plugins, which is what is +given as the second parameter to the plugin. As with all hooks, the usage of +the hook parameters and/or its return value are determined based on the +context in which the hook is used - you have to look at it in the SquirrelMail +core. Please remember NEVER to output any HTML directly during hook execution. Read more about the <tt/do_hook()/ function in the <url url="http://squirrelmail.org/docs/devel-code/squirrelmail/_functions---plugin.php.html#functiondo_hook" name="1.5 API documentation">. This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <pdo...@us...> - 2008-11-21 22:39:21
|
Revision: 13329 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13329&view=rev Author: pdontthink Date: 2008-11-21 22:39:18 +0000 (Fri, 21 Nov 2008) Log Message: ----------- Fix page width Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2008-11-21 19:47:11 UTC (rev 13328) +++ trunk/documentation/devel/devel.sgml 2008-11-21 22:39:18 UTC (rev 13329) @@ -2363,7 +2363,9 @@ ), ), 'summary' => 'Adds important information above the folder list.', - 'details' => 'This plugin automatically sees into the user\'s future and places important details about upcoming events above the folder list.', + 'details' => 'This plugin automatically sees into the user\'s ' + . 'future and places important details about upcoming ' + . 'events above the folder list.', 'version' => '2.5.1', 'required_sm_version' => '1.2.9', 'requires_configuration' => 0, This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <pdo...@us...> - 2008-12-04 05:55:37
|
Revision: 13343 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13343&view=rev Author: pdontthink Date: 2008-12-04 05:55:35 +0000 (Thu, 04 Dec 2008) Log Message: ----------- Miscellaneous updates to release process Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2008-12-04 04:51:40 UTC (rev 13342) +++ trunk/documentation/devel/devel.sgml 2008-12-04 05:55:35 UTC (rev 13343) @@ -3328,7 +3328,7 @@ <item><bf/Usual sanity/ Check the code over to make sure we are absolutely ready. <item><bf/Documentation/ Update Release Documents <enum> - <item> Make sure that the ChangeLog is up to date. + <item> Make sure that the ChangeLog is up to date - remember to put the release date in place of <tt/SVN/ at the top of the file. <item> Update the ReleaseNotes, keeping the same general format. <item> Compose a three to eight line message you'll post to mailinglists and forums. Include links. (While you're at it, make a simple HTML version of it as well, you'll need it later) Be BRIEF. Keep this message in your editor or on file for later on. </enum> @@ -3347,7 +3347,7 @@ https://squirrelmail.svn.sourceforge.net/svnroot/squirrelmail/tags/rel-1_2_1 </tscreen> <item> Use the script <tt>make-release</tt> <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/util/make-release" name="found in SVN"> under the <tt>util/</tt> dir. The only parameter - is the version to release. It will download the tagged SVN copy, pack it up nicely and upload it to SF.net. + is the version to release. It will download the tagged SVN copy, pack it up nicely and upload it to SF.net (CORRECTION - the upload commands are currently commented out, so you'll need to do that manually or edit the script to do that for you). You will need the following tools: bash, svn, ssh, curl, tar, gzip, zip, bzip2 and optionally rpmbuild. <item> Upload the release files to Sourceforge.net, see <url url="http://alexandria.wiki.sourceforge.net/File+Release+System+-+Offering+Files+for+Download#upload" name="sf.net instructions">. <item> (huh: don't go to sleep before you're finished making the release) @@ -3356,6 +3356,7 @@ <enum> <item> Go back to your regular SVN development directory. <item> Update the version number variable in functions/strings.php by incrementing the incremental release number by 1 and adding <tt>' [SVN]'</tt> after it (<tt>$version = '1.2.2 [SVN]';</tt>). + <item> Add a new section in ChangeLog for the new release, followed by <tt>' - SVN'</tt> <item> Archive the ReleaseNotes for this release like this: <tscreen>svn copy ReleaseNotes doc/ReleaseNotes/X.Y/Notes-X.Y.Z.txt</tscreen> <item> Commit all these changes to SVN with a note saying that it is ready for continued development. @@ -3404,7 +3405,7 @@ <enum> <item> Click on News in the SourceForge interface. <item> Add a news item for this release in the SourceForge news system. (The 3 to 8 line message you've made) - <item> Submit1 the news, go preview it, and fix it if you did something silly. :) + <item> Submit the news, go preview it, and fix it if you did something silly. :) </enum> <item> Add a news item to the SquirrelMail webpage. <enum> @@ -3415,7 +3416,9 @@ </enum> <item> Send a message to squirrelmail-announce telling people about the release. <enum> + <item> Also, currently, it seems to have become convention that the message gets sent to all our other mailing lists: <tt>squ...@li..., squ...@li..., squ...@li..., squ...@li..., squ...@li...</tt> <item> Again, use your brief 3 to 8 line message + <item> The subject should read "ANNOUNCE: SquirrelMail X.Y.Z Released" <item> Approve the message <enum> <item> Log in to the <url name="squirrelmail-announce administrative interface" This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <pdo...@us...> - 2009-02-20 21:26:36
|
Revision: 13410 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13410&view=rev Author: pdontthink Date: 2009-02-20 21:26:28 +0000 (Fri, 20 Feb 2009) Log Message: ----------- Provide link to know where to find team list Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2009-02-19 23:37:37 UTC (rev 13409) +++ trunk/documentation/devel/devel.sgml 2009-02-20 21:26:28 UTC (rev 13410) @@ -2650,7 +2650,9 @@ <sect2>Submitting the plugin <p> When the plugin is ready to be reviewed by the SquirrelMail plugin team, mail it -to the SquirrelMail plugins team members. +to the SquirrelMail plugin team members (who may be found by consulting the +<url url="http://www.squirrelmail.org/docs/devel/devel-1.html#ss1.2" +name="SquirrelMail team list">). When the plugin is approved and you're granted access to upload it, all you have to do is the actual uploading along with filling out some general information This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <pdo...@us...> - 2009-03-12 04:05:54
|
Revision: 13417 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13417&view=rev Author: pdontthink Date: 2009-03-12 04:05:49 +0000 (Thu, 12 Mar 2009) Log Message: ----------- Add chapter for adding new languages; make Project Admin section; rewrite $languages array chapter; update supported languages list; other smaller changes Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2009-03-11 20:35:56 UTC (rev 13416) +++ trunk/documentation/devel/devel.sgml 2009-03-12 04:05:49 UTC (rev 13417) @@ -770,7 +770,7 @@ This chapter should explain how SquirrelMail internationalization works and provide information about some aspects of implementation. -<sect1>Supported languages +<sect1>Supported Languages<label id="supported_languages"> <p> TODO: Remove statistics and add them dynamically to the i18n stat's page, using a script. @@ -795,6 +795,7 @@ <item>fi_FI - Finnish, iso-8859-1 charset <item>fo_FO - Faroese, iso-8859-1 charset <item>fr_FR - French, iso-8859-1 charset + <item>fy - Frisian, utf-8 charset <item>he_IL - Hebrew, windows-1255 charset <item>hr_HR - Croatian, iso-8859-2 charset <item>hu_HU - Hungarian, iso-8859-2 charset @@ -802,9 +803,11 @@ <item>is_IS - Icelandic, iso-8859-1 charset <item>it_IT - Italian, iso-8859-1 charset <item>ja_JP - Japanese, euc-jp charset (emails are created in iso-2022-jp) - <item>ka - Georgian, utf-8 charset (since 1.5.1 and 1.4.6) + <item>ka - Georgian, utf-8 charset (since 1.5.1 and 1.4.6) <item>ko_KR - Korean, euc-kr charset + <item>lv_LV - Latvian, utf-8 charset <item>lt_LT - Lithuanian, utf-8 charset + <item>mk - Macedonian, utf-8 charset <item>ms_MY - Malay, iso-8859-1 charset <item>nb_NO - Norwegian (Bokmal), iso-8859-1 charset <item>nl_NL - Dutch, iso-8859-1 charset @@ -815,15 +818,18 @@ <item>ro_RO - Romanian, iso-8859-2 charset <item>ru_UA - Ukrainian Russian, koi8-r charset <item>ru_RU - Russian, utf-8 charset + <item>si_LK - Sinhala, utf-8 charset <item>sk_SK - Slovak, iso-8859-2 charset <item>sl_SI - Slovenian, iso-8859-2 charset <item>sr_YU - Serbian, iso-8859-2 charset <item>sv_SE - Swedish, iso-8859-1 charset - <item>ug - Uighur, utf-8 charset (some systems don't support Uighur system locale) + <item>ta_SK - Tamil (Sri Lanka), utf-8 charset <item>th_TH - Thai, tis-620 charset <item>tl_PH - Tagalog, iso-8859-1 charset (main translation is missing, only some plugins are translated) <item>tr_TR - Turkish, iso-8859-9 charset + <item>ug - Uighur, utf-8 charset (some systems don't support Uighur system locale) <item>uk_UA - Ukrainian, koi8-u charset + <item>vi_VN - Vietnamese, utf-8 charset <item>zh_CN - Chinese Simplified, gb2312 charset <item>zh_TW - Chinese Traditional, big5 charset </itemize> @@ -832,7 +838,7 @@ <itemize> <item>iso-8859-1 = 21 <item>iso-8859-2 = 8 - <item>utf-8 = 6 + <item>utf-8 = 12 <item>iso-8859-15 = 2 <item>iso-8859-7 = 1 <item>iso-8859-9 = 1 @@ -846,47 +852,66 @@ <item>big5 = 1 <item>euc-jp = 1 <item>euc-kr = 1 + <item>TOTAL = 55 </itemize> -<sect1>The <tt>$languages</tt> array +<sect1>The <tt>$languages</tt> array<label id="languages_array"> <p> -The <tt>$languages</tt> array is stored in <tt>functions/i18n.php</tt> and defines translations -that are enabled in SquirrelMail. Since SquirrelMail 1.5.1 <tt>functions/i18n.php</tt> -stores only English entry. Other languages are loaded automatically from -<tt>locale/<language_code>/setup.php</tt> files. +The <tt>$languages</tt> array is defined in <tt>functions/i18n.php</tt> (which has been +moved to <tt>include/languages.php</tt> as of SquirrelMail 1.5.2) and defines translations +that are enabled in SquirrelMail. Starting with SquirrelMail 1.5.1, only the English +language entry is defined in the core; other languages are added automatically to the +<tt>$languages</tt> array from a file in the locale pack: +<tt>locale/<language_code>/setup.php</tt>. Format of array: <tscreen><verb> - $languages['language_code']['key'] = 'value' + $languages['language_code']['key'] = 'value'; </verb></tscreen> Possible array key names: <descrip> - <tag/NAME/ Translation name in English. Any 8bit symbols must be HTML encoded. - <tag/CHARSET/ Charset used by translation - <tag/ALIAS/ 'language_code' should contain short language name - (ISO-639). 'value' should contain name of other 'language_code' - that defines translation with NAME and CHARSET keys. - Entry links short language form with long form (language+country). - See: http://loc.gov/standards/iso639-2/langhome.html and - http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html - <tag/ALTNAME/ Native translation name. Any 8bit symbols must be HTML encoded. - Name is visible when $show_alternative_names is enabled. - <tag/LOCALE/ Full locale name (in xx_XX.charset format or other format required - by PHP gettext functions). From 1.4.4/1.5.1 'value' can contain - array. If PHP version is older than 4.3.0, system uses only first - locale name listed in array. First locale name must be compatible - with FreeBSD system locale names. - <tag/DIR/ Text direction. Used to define Right-to-Left languages. Possible - values 'rtl' or 'ltr'. If undefined - defaults to 'ltr'. - <tag/XTRA_CODE/ translation uses special functions. (see chapter about XTRA_CODE functions) + <tag/NAME/ The name of the language in English. HTML encoding must be used for + any 8-bit symbols. + <tag/ALTNAME/ The native language name (the name of the language in that language + itself). HTML encoding must be used for any 8-bit symbols. This name + is shown when <tt>$show_alternative_names</tt> is enabled in + <tt>config/config.php</tt> (or use the configuration utiltiy and + choose "10. Language settings" --> "3. Show alternative language names") + (for SquirrelMail 1.5.0 and up). + <tag/CHARSET/ The character set used for the translation. + <tag/LOCALE/ The full locale name (in "xx_XX.charset" format or other format required + by PHP gettext functions). Starting with 1.4.4/1.5.1 and up, 'value' can + contain an array. If the PHP version is older than 4.3.0, the system will + use only the first locale name listed in the array. The first locale name + must be compatible with the FreeBSD system locale names. Under all other + setups, if the first locale is not supported, SquirrelMail will continue + to try the other locales in the order given in this array. Developers + can check for supported locale names on their system by checking the + contents of, for example, <tt>/usr/lib/locale/</tt> (RedHat/Fedora). + <tag/ALIAS/ Any number of aliased language codes can be linked to a given translation + by creating one ALIAS entry for each link. The 'language_code' for the + alias should contain the aliased language code and the 'value' should + contain the language code SquirrelMail uses to store the actual translation. + For example, the <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/locale/nb_NO/setup.php?view=markup" name="Norwegian"> + Translation is stored in SquirrelMail as "nb_NO", but it also has an + alias for its ISO-639-1 code "nb". + See: <url url="http://loc.gov/standards/iso639-2/langhome.html" + name="ISO 639 list"> and + <url url="http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html" + name="country code list"> + <tag/DIR/ The text direction of the language. This is used to indicate + right-to-left languages and is not needed otherwise. Possible + values are 'rtl' or 'ltr' (when undefined, it defaults to 'ltr'). + <tag/XTRA_CODE/ Indicates that the translation uses special functions. (see + <ref id="language_xtra_code" name="chapter about XTRA_CODE functions">) </descrip> -Each 'language_code' definition requires NAME+CHARSET or ALIAS keys. Other keys are -optional. +Note that each 'language_code' definition requires at least the NAME and CHARSET keys +or just the ALIAS key. All other keys are optional. -<sect1>XTRA_CODE functions +<sect1>XTRA_CODE functions<label id="language_xtra_code"> <p> XTRA_CODE functions provide way to change interface behavior, when translation requires special handling of some SquirrelMail functions. Functions are enabled @@ -2658,6 +2683,147 @@ to do is the actual uploading along with filling out some general information about the plugin and what it does. +<sect>Project Administration +<p> +TODO: This section may still need cleanup and/or some conversion to LinuxDoc format. + +<sect1>Release Instructions +<p> + +<enum> +<item><bf/Teamwork:/ Before beginning, coordinate the release with other members of the admin list to ensure proper time for verification and testing of release components (RPM, etc). +<item><bf/Usual sanity:/ Check the code over to make sure we are absolutely ready. +<item><bf/Documentation:/ Update Release Documents + <enum> + <item> Make sure that the ChangeLog is up to date - remember to put the release date in place of <tt/SVN/ at the top of the file. + <item> Update the ReleaseNotes, keeping the same general format. + <item> Compose a three to eight line message you'll post to mailinglists and forums. Include links. (While you're at it, make a simple HTML version of it as well, you'll need it later) Be BRIEF. Keep this message in your editor or on file for later on. + </enum> +<item><bf/Gearing up:/ Update the version number strings at 3 places: + <enum> + <item> Variables in <tt>functions/strings.php</tt> (<tt>$version = '1.2.1', $SQM_INTERNAL_VERSION=array(1,2,1)</tt>). + <item> <tt>ChangeLog</tt> + <item> <tt>ReleaseNotes</tt> + </enum> +<item><bf/SVN packaging:/ + <enum> + <item> Commit final changes to Subversion (ChangeLog, ReleaseNotes, functions/strings.php) + <item> Tag SVN with the release number in the format rel-X_Y_Z (rel-1_2_1). Example: + <tscreen> +svn copy https://squirrelmail.svn.sourceforge.net/svnroot/squirrelmail/branches/SM-1_4-STABLE/squirrelmail \ + https://squirrelmail.svn.sourceforge.net/svnroot/squirrelmail/tags/rel-1_2_1 + </tscreen> + <item> Use the script <tt>make-release</tt> <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/util/make-release" name="found in SVN"> under the <tt>util/</tt> dir. The only parameter + is the version to release. It will download the tagged SVN copy, pack it up nicely and upload it to SF.net (CORRECTION - the upload commands are currently commented out, so you'll need to do that manually or edit the script to do that for you). + You will need the following tools: bash, svn, ssh, curl, tar, gzip, zip, bzip2 and optionally rpmbuild. + <item> Upload the release files to Sourceforge.net, see <url url="http://alexandria.wiki.sourceforge.net/File+Release+System+-+Offering+Files+for+Download#upload" name="sf.net instructions">. + <item> (huh: don't go to sleep before you're finished making the release) + </enum> +<item><bf/Defrosting:/ Prepare SVN for continued development + <enum> + <item> Go back to your regular SVN development directory. + <item> Update the version number variable in functions/strings.php by incrementing the incremental release number by 1 and adding <tt>' [SVN]'</tt> after it (<tt>$version = '1.2.2 [SVN]';</tt>). + <item> Add a new section in ChangeLog for the new release, followed by <tt>' - SVN'</tt> + <item> Archive the ReleaseNotes for this release like this: + <tscreen>svn copy ReleaseNotes doc/ReleaseNotes/X.Y/Notes-X.Y.Z.txt</tscreen> + <item> Commit all these changes to SVN with a note saying that it is ready for continued development. + </enum> +<item><bf/sf.net admin stuff:/ Post the release files on SourceForge (you need to be a "release technician" to do this) + <enum> + <item> Create the new release of files + <enum> + <item> Log into SourceForge and go to the Admin section, File Releases. + <item> Click on the "add release" button for the correct package. + <item> Enter the release name in the box show in X.Y.Z format (no SquirrelMail or anything, just X.Y.Z). + <item> The next page it shows you will be the same page you get to if you clicked on "edit release" from the "Edit/Release Files" page earlier and selected a release name. + </enum> + <item> Enter the ChangeLog and ReleaseNotes for this SourceForge file release. + <item> Add the newly uploaded files to the release + <enum> + <item> Go down to the "add files to this release" section + <item> Select the files you recently uploaded (be nice and leave other peoples files alone). + <item> Click the "Add Files and/or Refresh View" button. + </enum> + <item> For each files added (tar.gz, tar.bz2, and zip), one at a time, set the file info correctly. + <enum> + <item> Set the processor to 'Platform-Independent'. + <item> Set the file type (.bz2 for the tar.bz2 file, .gz for the tar.gz file, .zip for the zip file, and .rpm for the .rpm files). + <item> Click the "Update/Refresh" button for that file. + </enum> + <item> Annouce the file release to those monitoring it with the button on the bottom of the page. + </enum> +<item><bf/Enable downloading:/ Update the download page for the SquirrelMail website. + <enum> + <item> SSH into sciurida + <item> Change to the web directory for SquirrelMail (currently /srv/www/www/htdocs). + <item> Edit download.php and change the version number as necessary. This is a php variable in the top part of the file. + <item> Edit plugin_query.php file and change version number. This file informs pupdate plugin users about new release. + <item> Upload the md5sums that make-release calculated into the <tt>sums/</tt> dir. + </enum> +<item><bf/Get porting assistance:/ contact our people who know how to make decent .deb and .rpm files + <enum> + <item> For Debian, this is taken care of by Thijs Kinkhorst and Jeroen van Wolffelaar + <item> RPM's are created by Konstantin Ryabitsev + <item> Mail or IM them, and ask them very politlely to take the time to create their files. point them to the download page where they can already grab the .tar.gz + </enum> +<item><bf/Blatant yelling:/ Announce the release to the World. + <enum> + <item> Post the release to the SourceForge news system. (you need to be a "forum moderator" to do this) + <enum> + <item> Click on News in the SourceForge interface. + <item> Add a news item for this release in the SourceForge news system. (The 3 to 8 line message you've made) + <item> Submit the news, go preview it, and fix it if you did something silly. :) + </enum> + <item> Add a news item to the SquirrelMail webpage. + <enum> + <item> Go to the address <url name="http://squirrelmail.org/admin" url="http://squirrelmail.org/admin"> and log in. + <item> Click on news. + <item> Create a brief news item titled in the format 'ANNOUNCE: SquirrelMail X.Y.Z Released'. Use the three to eight line message (you have to use HTML, no wiki pretty formatting here). + <item> Submit the news, go preview it, and fix it if you did something silly. :) + </enum> + <item> Send a message to squirrelmail-announce telling people about the release. + <enum> + <item> Also, currently, it seems to have become convention that the message gets sent to all our other mailing lists: <tt>squ...@li..., squ...@li..., squ...@li..., squ...@li..., squ...@li...</tt> + <item> Again, use your brief 3 to 8 line message + <item> The subject should read "ANNOUNCE: SquirrelMail X.Y.Z Released" + <item> Approve the message + <enum> + <item> Log in to the <url name="squirrelmail-announce administrative interface" + url="http://lists.sourceforge.net/lists/admin/squirrelmail-announce">. + <item> Choose "Tend to pending administrative requests" + <item> Read the message, make sure you made no silly mistake whatsoever, and approve of it + <item> Log out + </enum> + </enum> + <item>Update <url name="freshmeat.net" url="http://freshmeat.net/projects/squirrelmail/">. + </enum> +</enum> + +<sect1>Adding New Languages +<p> + +<enum> +<item><bf/Validate the translation:/ Before beginning, there are several things that need to be verified for the translation to be acceptable: + <enum> + <item><bf/Copyright:/ Make sure it's OK to assign the copyright to the SquirrelMail project. We won't accept translations with other copyright holders. + <item><bf/Validate what was translated:/ The typical starting point for translating the SquirrelMail core is the most recent 1.4.x translation pack release squirrelmail.pot file, the most current of which is found in SVN <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/branches/SM-1_4_15/locales/po/squirrelmail.pot?view=markup" name="/branches/SM-1_4_15/locales/po">. However, the most comprehensive list of strings (for both STABLE and DEVEL) is always found in the SVN <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/po/" name="trunk locales">, which is also the starting point for making new language pack releases. + <item><bf/We want UTF-8:/ If the translation isn't already in UTF-8, push very hard to have the translator convert to UTF-8. SquirrelMail 1.5.x will soon be UTF-only, in which case we will stop accepting non-Unicode translations. + <item><bf/Inspect headers/ Compare the translation headers to one of the better ones already in the repository, such as Swedish (<url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/locale/sv_SE/LC_MESSAGES/squirrelmail.po?view=markup" name="sv_SE">). Ask the translator to fix any problems with the headers. + <item><bf/We want two letter ISO 639-1:/ If the translator has chosen a language code with attached region code, work with them to understand if the region code is necessary. If at all possible, we want languages with just the language code ("de" instead of "de_DE"; the latter is in the SquirrelMail repository only for legacy reasons). Check other projects to get an idea of the region code is needed such as <url url="http://l10n.kde.org/" name="KDE">, <url url="http://websvn.kde.org/trunk/l10n-kde4/" name="KDE">, Gnome, <url url="http://www.debian.org/international/l10n/po/" name="Debian">, Ubuntu, <url url="http://translate.fedoraproject.org/languages" name="Fedora">, Drupal, etc. Ideally, only the lower case two letter <url url="http://wikipedia.org/wiki/List_of_ISO_639-1_codes" name="ISO 639-1"> language code is used. If the region code is needed, make sure the language code is lower case and the region code is upper case ("de_DE"). + <item><bf/Sanity check:/ Have a look over the translation file(s) and make sure they look reasonable. + <item><bf/sec_remove image:/ Ask for a translated copy of the <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/squirrelmail/images/sec_remove_eng.png?view=markup" name="sec_remove_eng.png"> image file (renamed, of course, to sec_remove_<language>.png). + <item><bf/sec_remove strings:/ The sec_remove_eng.png string in the squirrelmail.po file should be "translated" to sec_remove_<language>.png. The string in the image itself ("This image has been removed for security reasons") is also in the .pot file and should be translated in the .po file. + </enum> +<item><bf/Create setup.php:/ Each language has its own setup.php file found in the top-level language directory (alongside LC_MESSAGES). A good starting point is to look at an existing example such as the Norwegian (<url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/locale/nb_NO/setup.php?view=markup" name="nb_NO">) one. See our <ref id="languages_array" name="explanation of the $languages array"> manual section. +<item><bf/Update i18n.php:/ Copy the contents of the language setup.php file created in the previous step into a block in the STABLE branch <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/branches/SM-1_4-STABLE/squirrelmail/functions/i18n.php?view=markup" name="functions/i18n.php"> file. +<item><bf/Place translations in SVN trunk:/ The main translations should go in SVN <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/locale/" name="trunk/locales/locale">/<language>/LC_MESSAGES. There are two directories in the LC_MESSAGES directory for most languages: "plugins", which contains translations for plugins that are still coded such that translation files need to be placed within the plugin itself (obsolete). The "extra" directory contains other translation files for broken things (mostly plugins with missing or incorrect internationalization efforts). These all correspond to the .pot files we provide, so where the translated files go should be rather obvious. Properly coded plugin translation files belong in the top-level LC_MESSAGES directory. +<item><bf/sec_remove image:/ The translated sec_remove image file should be placed in the main <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/images/" name="locales images"> directory. +<item><bf/Update SourceForge:/ Add the language to the list of supported translations on the SquirrelMail project page by logging in as an administrator and going to: "Project Admin" --> "Public Info" --> "Edit Trove Categorization" --> "Translations" +<item><bf/Update SquirrelMail manual:/ Update the supported languages list in the Developer's Manual (<ref id="supported_languages" name=""Supported Languages" in docs/devel/devel-3">). +<item><bf/Add translator(s):/ Add the translation maintainer(s) to the <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/TRANSLATORS?view=markup" name="TRANSLATORS"> file. +<item><bf/Changelog:/ Add the new translation to the Changelog for both STABLE and DEVEL. +</enum> + <sect>Miscellaneous <p> TODO: This is a quick and dirty import of the documents in "/doc/Development". @@ -3322,118 +3488,6 @@ walks the tree from the root node down to the leaves. </verb></tscreen> -<sect1>Release Instructions -<p> - -<enum> -<item><bf/Teamwork/ Before beginning, coordinate the release with other members of the admin list to ensure proper time for verification and testing of release components (RPM, etc). -<item><bf/Usual sanity/ Check the code over to make sure we are absolutely ready. -<item><bf/Documentation/ Update Release Documents - <enum> - <item> Make sure that the ChangeLog is up to date - remember to put the release date in place of <tt/SVN/ at the top of the file. - <item> Update the ReleaseNotes, keeping the same general format. - <item> Compose a three to eight line message you'll post to mailinglists and forums. Include links. (While you're at it, make a simple HTML version of it as well, you'll need it later) Be BRIEF. Keep this message in your editor or on file for later on. - </enum> -<item><bf/Gearing up/ Update the version number strings at 3 places: - <enum> - <item> Variables in <tt>functions/strings.php</tt> (<tt>$version = '1.2.1', $SQM_INTERNAL_VERSION=array(1,2,1)</tt>). - <item> <tt>ChangeLog</tt> - <item> <tt>ReleaseNotes</tt> - </enum> -<item><bf/SVN packaging/ - <enum> - <item> Commit final changes to Subversion (ChangeLog, ReleaseNotes, functions/strings.php) - <item> Tag SVN with the release number in the format rel-X_Y_Z (rel-1_2_1). Example: - <tscreen> -svn copy https://squirrelmail.svn.sourceforge.net/svnroot/squirrelmail/branches/SM-1_4-STABLE/squirrelmail \ - https://squirrelmail.svn.sourceforge.net/svnroot/squirrelmail/tags/rel-1_2_1 - </tscreen> - <item> Use the script <tt>make-release</tt> <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/util/make-release" name="found in SVN"> under the <tt>util/</tt> dir. The only parameter - is the version to release. It will download the tagged SVN copy, pack it up nicely and upload it to SF.net (CORRECTION - the upload commands are currently commented out, so you'll need to do that manually or edit the script to do that for you). - You will need the following tools: bash, svn, ssh, curl, tar, gzip, zip, bzip2 and optionally rpmbuild. - <item> Upload the release files to Sourceforge.net, see <url url="http://alexandria.wiki.sourceforge.net/File+Release+System+-+Offering+Files+for+Download#upload" name="sf.net instructions">. - <item> (huh: don't go to sleep before you're finished making the release) - </enum> -<item><bf/Defrosting/ Prepare SVN for continued development - <enum> - <item> Go back to your regular SVN development directory. - <item> Update the version number variable in functions/strings.php by incrementing the incremental release number by 1 and adding <tt>' [SVN]'</tt> after it (<tt>$version = '1.2.2 [SVN]';</tt>). - <item> Add a new section in ChangeLog for the new release, followed by <tt>' - SVN'</tt> - <item> Archive the ReleaseNotes for this release like this: - <tscreen>svn copy ReleaseNotes doc/ReleaseNotes/X.Y/Notes-X.Y.Z.txt</tscreen> - <item> Commit all these changes to SVN with a note saying that it is ready for continued development. - </enum> -<item><bf/sf.net admin stuff/ Post the release files on SourceForge (you need to be a "release technician" to do this) - <enum> - <item> Create the new release of files - <enum> - <item> Log into SourceForge and go to the Admin section, File Releases. - <item> Click on the "add release" button for the correct package. - <item> Enter the release name in the box show in X.Y.Z format (no SquirrelMail or anything, just X.Y.Z). - <item> The next page it shows you will be the same page you get to if you clicked on "edit release" from the "Edit/Release Files" page earlier and selected a release name. - </enum> - <item> Enter the ChangeLog and ReleaseNotes for this SourceForge file release. - <item> Add the newly uploaded files to the release - <enum> - <item> Go down to the "add files to this release" section - <item> Select the files you recently uploaded (be nice and leave other peoples files alone). - <item> Click the "Add Files and/or Refresh View" button. - </enum> - <item> For each files added (tar.gz, tar.bz2, and zip), one at a time, set the file info correctly. - <enum> - <item> Set the processor to 'Platform-Independent'. - <item> Set the file type (.bz2 for the tar.bz2 file, .gz for the tar.gz file, .zip for the zip file, and .rpm for the .rpm files). - <item> Click the "Update/Refresh" button for that file. - </enum> - <item> Annouce the file release to those monitoring it with the button on the bottom of the page. - </enum> -<item><bf/Enable downloading/ Update the download page for the SquirrelMail website. - <enum> - <item> SSH into sciurida - <item> Change to the web directory for SquirrelMail (currently /srv/www/www/htdocs). - <item> Edit download.php and change the version number as necessary. This is a php variable in the top part of the file. - <item> Edit plugin_query.php file and change version number. This file informs pupdate plugin users about new release. - <item> Upload the md5sums that make-release calculated into the <tt>sums/</tt> dir. - </enum> -<item><bf/Get porting assistance/ contact our people who know how to make decent .deb and .rpm files - <enum> - <item> For Debian, this is taken care of by Thijs Kinkhorst and Jeroen van Wolffelaar - <item> RPM's are created by Konstantin Ryabitsev - <item> Mail or IM them, and ask them very politlely to take the time to create their files. point them to the download page where they can already grab the .tar.gz - </enum> -<item><bf/Blatant yelling/ Announce the release to the World. - <enum> - <item> Post the release to the SourceForge news system. (you need to be a "forum moderator" to do this) - <enum> - <item> Click on News in the SourceForge interface. - <item> Add a news item for this release in the SourceForge news system. (The 3 to 8 line message you've made) - <item> Submit the news, go preview it, and fix it if you did something silly. :) - </enum> - <item> Add a news item to the SquirrelMail webpage. - <enum> - <item> Go to the address <url name="http://squirrelmail.org/admin" url="http://squirrelmail.org/admin"> and log in. - <item> Click on news. - <item> Create a brief news item titled in the format 'ANNOUNCE: SquirrelMail X.Y.Z Released'. Use the three to eight line message (you have to use HTML, no wiki pretty formatting here). - <item> Submit the news, go preview it, and fix it if you did something silly. :) - </enum> - <item> Send a message to squirrelmail-announce telling people about the release. - <enum> - <item> Also, currently, it seems to have become convention that the message gets sent to all our other mailing lists: <tt>squ...@li..., squ...@li..., squ...@li..., squ...@li..., squ...@li...</tt> - <item> Again, use your brief 3 to 8 line message - <item> The subject should read "ANNOUNCE: SquirrelMail X.Y.Z Released" - <item> Approve the message - <enum> - <item> Log in to the <url name="squirrelmail-announce administrative interface" - url="http://lists.sourceforge.net/lists/admin/squirrelmail-announce">. - <item> Choose "Tend to pending administrative requests" - <item> Read the message, make sure you made no silly mistake whatsoever, and approve of it - <item> Log out - </enum> - </enum> - <item>Update <url name="freshmeat.net" url="http://freshmeat.net/projects/squirrelmail/">. - </enum> -</enum> - <appendix> <sect>Links This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <pdo...@us...> - 2009-03-12 04:30:32
|
Revision: 13418 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13418&view=rev Author: pdontthink Date: 2009-03-12 04:30:24 +0000 (Thu, 12 Mar 2009) Log Message: ----------- Typo Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2009-03-12 04:05:49 UTC (rev 13417) +++ trunk/documentation/devel/devel.sgml 2009-03-12 04:30:24 UTC (rev 13418) @@ -823,7 +823,7 @@ <item>sl_SI - Slovenian, iso-8859-2 charset <item>sr_YU - Serbian, iso-8859-2 charset <item>sv_SE - Swedish, iso-8859-1 charset - <item>ta_SK - Tamil (Sri Lanka), utf-8 charset + <item>ta_LK - Tamil (Sri Lanka), utf-8 charset <item>th_TH - Thai, tis-620 charset <item>tl_PH - Tagalog, iso-8859-1 charset (main translation is missing, only some plugins are translated) <item>tr_TR - Turkish, iso-8859-9 charset This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <pdo...@us...> - 2009-03-12 05:34:54
|
Revision: 13419 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13419&view=rev Author: pdontthink Date: 2009-03-12 05:34:40 +0000 (Thu, 12 Mar 2009) Log Message: ----------- Add info about making gpg sigs for releases Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2009-03-12 04:30:24 UTC (rev 13418) +++ trunk/documentation/devel/devel.sgml 2009-03-12 05:34:40 UTC (rev 13419) @@ -2685,7 +2685,6 @@ <sect>Project Administration <p> -TODO: This section may still need cleanup and/or some conversion to LinuxDoc format. <sect1>Release Instructions <p> @@ -2698,7 +2697,7 @@ <item> Make sure that the ChangeLog is up to date - remember to put the release date in place of <tt/SVN/ at the top of the file. <item> Update the ReleaseNotes, keeping the same general format. <item> Compose a three to eight line message you'll post to mailinglists and forums. Include links. (While you're at it, make a simple HTML version of it as well, you'll need it later) Be BRIEF. Keep this message in your editor or on file for later on. - </enum> + </enum> <item><bf/Gearing up:/ Update the version number strings at 3 places: <enum> <item> Variables in <tt>functions/strings.php</tt> (<tt>$version = '1.2.1', $SQM_INTERNAL_VERSION=array(1,2,1)</tt>). @@ -2716,7 +2715,17 @@ <item> Use the script <tt>make-release</tt> <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/util/make-release" name="found in SVN"> under the <tt>util/</tt> dir. The only parameter is the version to release. It will download the tagged SVN copy, pack it up nicely and upload it to SF.net (CORRECTION - the upload commands are currently commented out, so you'll need to do that manually or edit the script to do that for you). You will need the following tools: bash, svn, ssh, curl, tar, gzip, zip, bzip2 and optionally rpmbuild. - <item> Upload the release files to Sourceforge.net, see <url url="http://alexandria.wiki.sourceforge.net/File+Release+System+-+Offering+Files+for+Download#upload" name="sf.net instructions">. + <item> Create a GPG signature for each of the newly created release packages. Typically, this can be done with: + <enum> + <item><tt>gpg -a --detach-sign --output squirrelmail-X.Y.Z.tar.gz.sig squirrelmail-X.Y.Z.tar.gz</tt> + <item><tt>gpg -a --detach-sign --output squirrelmail-X.Y.Z.tar.bz2.sig squirrelmail-X.Y.Z.tar.bz2</tt> + <item><tt>gpg -a --detach-sign --output squirrelmail-X.Y.Z.zip.sig squirrelmail-X.Y.Z.zip</tt> + </enum> + An example for how to verify that your signature worked would be: + <enum> + <item><tt>gpg --verify squirrelmail-X.Y.Z.tar.gz.sig squirrelmail-X.Y.Z.tar.gz</tt> + </enum> + <item> Upload the release files (including the md5, sha and GPG signatures) to Sourceforge.net, see <url url="http://alexandria.wiki.sourceforge.net/File+Release+System+-+Offering+Files+for+Download#upload" name="sf.net instructions">. <item> (huh: don't go to sleep before you're finished making the release) </enum> <item><bf/Defrosting:/ Prepare SVN for continued development This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <pdo...@us...> - 2009-03-12 22:41:11
|
Revision: 13420 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13420&view=rev Author: pdontthink Date: 2009-03-12 22:41:05 +0000 (Thu, 12 Mar 2009) Log Message: ----------- Add teamnames file update; reorganize to make sgml more readable Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2009-03-12 05:34:40 UTC (rev 13419) +++ trunk/documentation/devel/devel.sgml 2009-03-12 22:41:05 UTC (rev 13420) @@ -2812,24 +2812,98 @@ <p> <enum> -<item><bf/Validate the translation:/ Before beginning, there are several things that need to be verified for the translation to be acceptable: +<item><bf/Validate the translation:/ Before beginning, there are several things + that need to be verified for the translation to be acceptable: <enum> - <item><bf/Copyright:/ Make sure it's OK to assign the copyright to the SquirrelMail project. We won't accept translations with other copyright holders. - <item><bf/Validate what was translated:/ The typical starting point for translating the SquirrelMail core is the most recent 1.4.x translation pack release squirrelmail.pot file, the most current of which is found in SVN <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/branches/SM-1_4_15/locales/po/squirrelmail.pot?view=markup" name="/branches/SM-1_4_15/locales/po">. However, the most comprehensive list of strings (for both STABLE and DEVEL) is always found in the SVN <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/po/" name="trunk locales">, which is also the starting point for making new language pack releases. - <item><bf/We want UTF-8:/ If the translation isn't already in UTF-8, push very hard to have the translator convert to UTF-8. SquirrelMail 1.5.x will soon be UTF-only, in which case we will stop accepting non-Unicode translations. - <item><bf/Inspect headers/ Compare the translation headers to one of the better ones already in the repository, such as Swedish (<url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/locale/sv_SE/LC_MESSAGES/squirrelmail.po?view=markup" name="sv_SE">). Ask the translator to fix any problems with the headers. - <item><bf/We want two letter ISO 639-1:/ If the translator has chosen a language code with attached region code, work with them to understand if the region code is necessary. If at all possible, we want languages with just the language code ("de" instead of "de_DE"; the latter is in the SquirrelMail repository only for legacy reasons). Check other projects to get an idea of the region code is needed such as <url url="http://l10n.kde.org/" name="KDE">, <url url="http://websvn.kde.org/trunk/l10n-kde4/" name="KDE">, Gnome, <url url="http://www.debian.org/international/l10n/po/" name="Debian">, Ubuntu, <url url="http://translate.fedoraproject.org/languages" name="Fedora">, Drupal, etc. Ideally, only the lower case two letter <url url="http://wikipedia.org/wiki/List_of_ISO_639-1_codes" name="ISO 639-1"> language code is used. If the region code is needed, make sure the language code is lower case and the region code is upper case ("de_DE"). - <item><bf/Sanity check:/ Have a look over the translation file(s) and make sure they look reasonable. - <item><bf/sec_remove image:/ Ask for a translated copy of the <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/squirrelmail/images/sec_remove_eng.png?view=markup" name="sec_remove_eng.png"> image file (renamed, of course, to sec_remove_<language>.png). - <item><bf/sec_remove strings:/ The sec_remove_eng.png string in the squirrelmail.po file should be "translated" to sec_remove_<language>.png. The string in the image itself ("This image has been removed for security reasons") is also in the .pot file and should be translated in the .po file. + <item><bf/Copyright:/ Make sure it's OK to assign the copyright to the + SquirrelMail project. We won't accept translations with other + copyright holders. + <item><bf/Validate what was translated:/ The typical starting point for + translating the SquirrelMail core is the most recent 1.4.x + translation pack release squirrelmail.pot file, the most current + of which is found in SVN + <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/branches/SM-1_4_15/locales/po/squirrelmail.pot?view=markup" + name="/branches/SM-1_4_15/locales/po">. However, the most + comprehensive list of strings (for both STABLE and DEVEL) is + always found in the SVN + <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/po/" + name="trunk locales">, which is also the starting point for making + new language pack releases. + <item><bf/We want UTF-8:/ If the translation isn't already in UTF-8, push + very hard to have the translator convert to UTF-8. SquirrelMail + 1.5.x will soon be UTF-only, in which case we will stop accepting + non-Unicode translations. + <item><bf/Inspect headers/ Compare the translation headers to one of the + better ones already in the repository, such as Swedish + (<url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/locale/sv_SE/LC_MESSAGES/squirrelmail.po?view=markup" + name="sv_SE">). Ask the translator to fix any problems with the + headers. + <item><bf/We want two letter ISO 639-1:/ If the translator has chosen a + language code with attached region code, work with them to understand + if the region code is necessary. If at all possible, we want + languages with just the language code ("de" instead of "de_DE"; + the latter is in the SquirrelMail repository only for legacy + reasons). Check other projects to get an idea of the region code + is needed such as <url url="http://l10n.kde.org/" name="KDE">, + <url url="http://websvn.kde.org/trunk/l10n-kde4/" name="KDE">, + Gnome, <url url="http://www.debian.org/international/l10n/po/" + name="Debian">, Ubuntu, + <url url="http://translate.fedoraproject.org/languages" name="Fedora">, + Drupal, etc. Ideally, only the lower case two letter + <url url="http://wikipedia.org/wiki/List_of_ISO_639-1_codes" + name="ISO 639-1"> language code is used. If the region code is + needed, make sure the language code is lower case and the region + code is upper case ("de_DE"). + <item><bf/Sanity check:/ Have a look over the translation file(s) and make + sure they look reasonable. + <item><bf/sec_remove image:/ Ask for a translated copy of the + <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/squirrelmail/images/sec_remove_eng.png?view=markup" + name="sec_remove_eng.png"> image file (renamed, of course, to + sec_remove_<language>.png). + <item><bf/sec_remove strings:/ The sec_remove_eng.png string in the + squirrelmail.po file should be "translated" to + sec_remove_<language>.png. The string in the image itself + ("This image has been removed for security reasons") is also in + the .pot file and should be translated in the .po file. </enum> -<item><bf/Create setup.php:/ Each language has its own setup.php file found in the top-level language directory (alongside LC_MESSAGES). A good starting point is to look at an existing example such as the Norwegian (<url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/locale/nb_NO/setup.php?view=markup" name="nb_NO">) one. See our <ref id="languages_array" name="explanation of the $languages array"> manual section. -<item><bf/Update i18n.php:/ Copy the contents of the language setup.php file created in the previous step into a block in the STABLE branch <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/branches/SM-1_4-STABLE/squirrelmail/functions/i18n.php?view=markup" name="functions/i18n.php"> file. -<item><bf/Place translations in SVN trunk:/ The main translations should go in SVN <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/locale/" name="trunk/locales/locale">/<language>/LC_MESSAGES. There are two directories in the LC_MESSAGES directory for most languages: "plugins", which contains translations for plugins that are still coded such that translation files need to be placed within the plugin itself (obsolete). The "extra" directory contains other translation files for broken things (mostly plugins with missing or incorrect internationalization efforts). These all correspond to the .pot files we provide, so where the translated files go should be rather obvious. Properly coded plugin translation files belong in the top-level LC_MESSAGES directory. -<item><bf/sec_remove image:/ The translated sec_remove image file should be placed in the main <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/images/" name="locales images"> directory. -<item><bf/Update SourceForge:/ Add the language to the list of supported translations on the SquirrelMail project page by logging in as an administrator and going to: "Project Admin" --> "Public Info" --> "Edit Trove Categorization" --> "Translations" -<item><bf/Update SquirrelMail manual:/ Update the supported languages list in the Developer's Manual (<ref id="supported_languages" name=""Supported Languages" in docs/devel/devel-3">). -<item><bf/Add translator(s):/ Add the translation maintainer(s) to the <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/TRANSLATORS?view=markup" name="TRANSLATORS"> file. +<item><bf/Create setup.php:/ Each language has its own setup.php file found in + the top-level language directory (alongside LC_MESSAGES). A good starting + point is to look at an existing example such as the Norwegian + (<url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/locale/nb_NO/setup.php?view=markup" + name="nb_NO">) one. See our <ref id="languages_array" name="explanation of + the $languages array"> manual section. +<item><bf/Update i18n.php:/ Copy the contents of the language setup.php file created + in the previous step into a block in the STABLE branch + <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/branches/SM-1_4-STABLE/squirrelmail/functions/i18n.php?view=markup" + name="functions/i18n.php"> file. +<item><bf/Place translations in SVN trunk:/ The main translations should go in SVN + <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/locale/" + name="trunk/locales/locale">/<language>/LC_MESSAGES. There are two + directories in the LC_MESSAGES directory for most languages: "plugins", + which contains translations for plugins that are still coded such that + translation files need to be placed within the plugin itself (obsolete). + The "extra" directory contains other translation files for broken things + (mostly plugins with missing or incorrect internationalization efforts). + These all correspond to the .pot files we provide, so where the translated + files go should be rather obvious. Properly coded plugin translation files + belong in the top-level LC_MESSAGES directory. +<item><bf/sec_remove image:/ The translated sec_remove image file should be placed + in the main + <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/images/" + name="locales images"> directory. +<item><bf/Update SourceForge:/ Add the language to the list of supported translations + on the SquirrelMail project page by logging in as an administrator and going + to: "Project Admin" --> "Public Info" --> "Edit Trove Categorization" + --> "Translations" +<item><bf/Update SquirrelMail manual:/ Update the supported languages list in the + Developer's Manual (<ref id="supported_languages" + name=""Supported Languages" in docs/devel/devel-3">). +<item><bf/Add translator(s):/ Add the translation maintainer(s) to the + <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/TRANSLATORS?view=markup" + name="TRANSLATORS"> file. +<item><bf/Update statistics:/ Add the translation team to the + <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/teamnames?view=markup" + name="teamnames"> file. <item><bf/Changelog:/ Add the new translation to the Changelog for both STABLE and DEVEL. </enum> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <pdo...@us...> - 2009-03-12 22:54:34
|
Revision: 13422 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13422&view=rev Author: pdontthink Date: 2009-03-12 22:54:33 +0000 (Thu, 12 Mar 2009) Log Message: ----------- Synch Persian language name Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2009-03-12 22:42:29 UTC (rev 13421) +++ trunk/documentation/devel/devel.sgml 2009-03-12 22:54:33 UTC (rev 13422) @@ -791,7 +791,7 @@ <item>es_ES - Spanish, iso-8859-1 charset <item>et_EE - Estonian, iso-8859-15 charset <item>eu_ES - Basque, iso-8859-1 charset - <item>fa_IR - Farsi, utf-8 charset + <item>fa_IR - Persian (Farsi), utf-8 charset <item>fi_FI - Finnish, iso-8859-1 charset <item>fo_FO - Faroese, iso-8859-1 charset <item>fr_FR - French, iso-8859-1 charset This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <pdo...@us...> - 2009-03-13 01:16:12
|
Revision: 13423 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13423&view=rev Author: pdontthink Date: 2009-03-13 01:16:02 +0000 (Fri, 13 Mar 2009) Log Message: ----------- note .mo files don't go in SVN Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2009-03-12 22:54:33 UTC (rev 13422) +++ trunk/documentation/devel/devel.sgml 2009-03-13 01:16:02 UTC (rev 13423) @@ -2876,7 +2876,8 @@ in the previous step into a block in the STABLE branch <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/branches/SM-1_4-STABLE/squirrelmail/functions/i18n.php?view=markup" name="functions/i18n.php"> file. -<item><bf/Place translations in SVN trunk:/ The main translations should go in SVN +<item><bf/Place translations in SVN trunk:/ The main translations (.po files - .mo + files don't belong in SVN) should go in SVN <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/locale/" name="trunk/locales/locale">/<language>/LC_MESSAGES. There are two directories in the LC_MESSAGES directory for most languages: "plugins", This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <pdo...@us...> - 2009-03-13 01:58:18
|
Revision: 13426 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13426&view=rev Author: pdontthink Date: 2009-03-13 01:44:39 +0000 (Fri, 13 Mar 2009) Log Message: ----------- Adding Bengali (Bangladesh) translation. Many thanks to Jamil Ahmed Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2009-03-13 01:37:44 UTC (rev 13425) +++ trunk/documentation/devel/devel.sgml 2009-03-13 01:44:39 UTC (rev 13426) @@ -779,7 +779,8 @@ <itemize> <item>ar - Arabic, windows-1256 charset <item>bg_BG - Bulgarian, windows-1251 charset - <item>bn_IN - Bengali, utf-8 charset + <item>bn_BD - Bangladeshi Bengali, utf-8 charset + <item>bn_IN - Indian Bengali, utf-8 charset <item>ca_ES - Catalan, iso-8859-1 charset <item>cs_CZ - Czech, iso-8859-2 charset <item>cy_GB - Welsh, iso-8859-1 charset @@ -838,7 +839,7 @@ <itemize> <item>iso-8859-1 = 21 <item>iso-8859-2 = 8 - <item>utf-8 = 12 + <item>utf-8 = 13 <item>iso-8859-15 = 2 <item>iso-8859-7 = 1 <item>iso-8859-9 = 1 @@ -852,7 +853,7 @@ <item>big5 = 1 <item>euc-jp = 1 <item>euc-kr = 1 - <item>TOTAL = 55 + <item>TOTAL = 56 </itemize> <sect1>The <tt>$languages</tt> array<label id="languages_array"> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <pdo...@us...> - 2009-03-24 23:05:13
|
Revision: 13437 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13437&view=rev Author: pdontthink Date: 2009-03-24 23:05:09 +0000 (Tue, 24 Mar 2009) Log Message: ----------- Another release bullet Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2009-03-17 21:23:46 UTC (rev 13436) +++ trunk/documentation/devel/devel.sgml 2009-03-24 23:05:09 UTC (rev 13437) @@ -2806,6 +2806,7 @@ </enum> </enum> <item>Update <url name="freshmeat.net" url="http://freshmeat.net/projects/squirrelmail/">. + <item>Update <url name="Wikipedia" url="http://en.wikipedia.org/wiki/SquirrelMail">. </enum> </enum> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <pdo...@us...> - 2009-03-27 09:30:52
|
Revision: 13483 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13483&view=rev Author: pdontthink Date: 2009-03-27 09:30:38 +0000 (Fri, 27 Mar 2009) Log Message: ----------- Update to reflect the new location of ChangeLog and ReleaseNotes Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2009-03-27 07:13:56 UTC (rev 13482) +++ trunk/documentation/devel/devel.sgml 2009-03-27 09:30:38 UTC (rev 13483) @@ -2702,12 +2702,12 @@ <item><bf/Gearing up:/ Update the version number strings at 3 places: <enum> <item> Variables in <tt>functions/strings.php</tt> (<tt>$version = '1.2.1', $SQM_INTERNAL_VERSION=array(1,2,1)</tt>). - <item> <tt>ChangeLog</tt> - <item> <tt>ReleaseNotes</tt> + <item> <tt>doc/ChangeLog</tt> + <item> <tt>doc/ReleaseNotes</tt> </enum> <item><bf/SVN packaging:/ <enum> - <item> Commit final changes to Subversion (ChangeLog, ReleaseNotes, functions/strings.php) + <item> Commit final changes to Subversion (doc/ChangeLog, doc/ReleaseNotes, functions/strings.php) <item> Tag SVN with the release number in the format rel-X_Y_Z (rel-1_2_1). Example: <tscreen> svn copy https://squirrelmail.svn.sourceforge.net/svnroot/squirrelmail/branches/SM-1_4-STABLE/squirrelmail \ @@ -2733,9 +2733,9 @@ <enum> <item> Go back to your regular SVN development directory. <item> Update the version number variable in functions/strings.php by incrementing the incremental release number by 1 and adding <tt>' [SVN]'</tt> after it (<tt>$version = '1.2.2 [SVN]';</tt>). - <item> Add a new section in ChangeLog for the new release, followed by <tt>' - SVN'</tt> - <item> Archive the ReleaseNotes for this release like this: - <tscreen>svn copy ReleaseNotes doc/ReleaseNotes/X.Y/Notes-X.Y.Z.txt</tscreen> + <item> Add a new section in doc/ChangeLog for the new release, followed by <tt>' - SVN'</tt> + <item> Archive the doc/ReleaseNotes for this release like this: + <tscreen>svn copy doc/ReleaseNotes doc/release_notes_archive/X.Y/Notes-X.Y.Z.txt</tscreen> <item> Commit all these changes to SVN with a note saying that it is ready for continued development. </enum> <item><bf/sf.net admin stuff:/ Post the release files on SourceForge (you need to be a "release technician" to do this) This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <jer...@us...> - 2009-04-08 05:19:46
|
Revision: 13533 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13533&view=rev Author: jervfors Date: 2009-04-08 05:19:44 +0000 (Wed, 08 Apr 2009) Log Message: ----------- Some minor formatting. Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2009-04-08 04:46:51 UTC (rev 13532) +++ trunk/documentation/devel/devel.sgml 2009-04-08 05:19:44 UTC (rev 13533) @@ -2818,11 +2818,11 @@ that need to be verified for the translation to be acceptable: <enum> <item><bf/Copyright:/ Make sure it's OK to assign the copyright to the - SquirrelMail project. We won't accept translations with other + SquirrelMail Project. We won't accept translations with other copyright holders. <item><bf/Validate what was translated:/ The typical starting point for translating the SquirrelMail core is the most recent 1.4.x - translation pack release squirrelmail.pot file, the most current + translation pack release <tt>squirrelmail.pot</tt> file, the most current of which is found in SVN <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/branches/SM-1_4_15/locales/po/squirrelmail.pot?view=markup" name="/branches/SM-1_4_15/locales/po">. However, the most @@ -2855,41 +2855,41 @@ <url url="http://wikipedia.org/wiki/List_of_ISO_639-1_codes" name="ISO 639-1"> language code is used. If the region code is needed, make sure the language code is lower case and the region - code is upper case ("de_DE"). + code is upper case ("pt_BR"). <item><bf/Sanity check:/ Have a look over the translation file(s) and make sure they look reasonable. <item><bf/sec_remove image:/ Ask for a translated copy of the - <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/squirrelmail/images/sec_remove_eng.png?view=markup" - name="sec_remove_eng.png"> image file (renamed, of course, to - sec_remove_<language>.png). - <item><bf/sec_remove strings:/ The sec_remove_eng.png string in the - squirrelmail.po file should be "translated" to - sec_remove_<language>.png. The string in the image itself + <tt><url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/squirrelmail/images/sec_remove_eng.png?view=markup" + name="sec_remove_eng.png"></tt> image file (renamed, of course, to + <tt>sec_remove_<language>.png</tt>). + <item><bf/sec_remove strings:/ The <tt>sec_remove_eng.png</tt> string in the + <tt>squirrelmail.po</tt> file should be "translated" to + <tt>sec_remove_<language>.png</tt>. The string in the image itself ("This image has been removed for security reasons") is also in - the .pot file and should be translated in the .po file. + the <tt>.pot</tt> file and should be translated in the <tt>.po</tt> file. </enum> -<item><bf/Create setup.php:/ Each language has its own setup.php file found in - the top-level language directory (alongside LC_MESSAGES). A good starting +<item><bf>Create <tt>setup.php</tt>:</bf> Each language has its own <tt>setup.php</tt> file found in + the top-level language directory (alongside <tt>LC_MESSAGES</tt>). A good starting point is to look at an existing example such as the Norwegian (<url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/locale/nb_NO/setup.php?view=markup" name="nb_NO">) one. See our <ref id="languages_array" name="explanation of the $languages array"> manual section. -<item><bf/Update i18n.php:/ Copy the contents of the language setup.php file created +<item><bf>Update <tt>i18n.php</tt>:</bf> Copy the contents of the language <tt>setup.php</tt> file created in the previous step into a block in the STABLE branch - <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/branches/SM-1_4-STABLE/squirrelmail/functions/i18n.php?view=markup" - name="functions/i18n.php"> file. -<item><bf/Place translations in SVN trunk:/ The main translations (.po files - .mo + <tt><url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/branches/SM-1_4-STABLE/squirrelmail/functions/i18n.php?view=markup" + name="functions/i18n.php"></tt> file. +<item><bf/Place translations in SVN trunk:/ The main translations (<tt>.po</tt> files - <tt>.mo</tt> files don't belong in SVN) should go in SVN - <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/locale/" - name="trunk/locales/locale">/<language>/LC_MESSAGES. There are two - directories in the LC_MESSAGES directory for most languages: "plugins", + <tt><url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/locale/" + name="trunk/locales/locale">/<language>/LC_MESSAGES</tt>. There are two + directories in the <tt>LC_MESSAGES</tt> directory for most languages: "plugins", which contains translations for plugins that are still coded such that translation files need to be placed within the plugin itself (obsolete). The "extra" directory contains other translation files for broken things (mostly plugins with missing or incorrect internationalization efforts). - These all correspond to the .pot files we provide, so where the translated + These all correspond to the <tt>.pot</tt> files we provide, so where the translated files go should be rather obvious. Properly coded plugin translation files - belong in the top-level LC_MESSAGES directory. + belong in the top-level <tt>LC_MESSAGES</tt> directory. <item><bf/sec_remove image:/ The translated sec_remove image file should be placed in the main <url url="http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/locales/images/" This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <jer...@us...> - 2009-04-09 14:36:13
|
Revision: 13534 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13534&view=rev Author: jervfors Date: 2009-04-09 14:36:01 +0000 (Thu, 09 Apr 2009) Log Message: ----------- Minor changes in formatting and wording. Adding a TODO about "plugin_hooks.php". Fixing a link. Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2009-04-08 05:19:44 UTC (rev 13533) +++ trunk/documentation/devel/devel.sgml 2009-04-09 14:36:01 UTC (rev 13534) @@ -1185,13 +1185,13 @@ <p> One of the most fun parts about programming is seeing an idea turn into a working product - the transition from "what if SquirrelMail could do..." -to "SquirrelMail CAN do...." The SquirrelMail team can appreciate and +to "SquirrelMail <em/can/ do..." The SquirrelMail team can appreciate and relate to that kind of enthusiasm, but we also don't want to see it go to waste. Therefore, the first thing to be done before considering the development of a new plugin (for public consumption at least) is to ask the SquirrelMail team if anyone has already attempted to implement the idea. It is also extremely helpful to announce your intentions in public so that the -SquirrelMail community can provide feedback and help refine the idea BEFORE +SquirrelMail community can provide feedback and help refine the idea <em/before/ it is implemented. Additionally, in keeping with the SquirrelMail theme of providing a product @@ -1200,7 +1200,7 @@ an administrator to understand what plugin is the right one for them. Plugins that contain similar feature sets should be merged and authors should work collaboratively instead of duplicating each others' efforts. If there -is a plugin on the SquirrelMail web site that <it/almost/ does what you +is a plugin on the SquirrelMail web site that <em/almost/ does what you want to do, please inquire with its author and/or the SquirrelMail team about enhancing it with your ideas. @@ -1208,16 +1208,16 @@ <p> The plugin architecture of SquirrelMail is designed to make it possible to add new features without having to patch SquirrelMail itself. Functionality like -changing user passowrds, displaying ads and calendars should be possible to add +changing user passwords, displaying ads, and calendars should be possible to add as plugins. In this scheme, either package (SquirrelMail or a plugin) may be upgraded independently without risk of one breaking the other. <sect2>The idea <p> -The idea is to be able to run random (plugin) code at given places in the -SquirrelMail core. This random code should then be able to do whatever is -needed to enhance the functionality of SquirrelMail. The places where plugin -code can be executed are called "hooks". +The idea is to be able to run plugin code at given places in the SquirrelMail +core. The plugin code should then be able to do whatever is needed to enhance +the functionality of SquirrelMail. The places where plugin code can be executed +are called "hooks". There are some limitations with what these hooks can do. It is difficult to use them to change the layout and to change functionality that already is in @@ -1262,6 +1262,8 @@ re-run the SquirrelMail configuraion utility or manually edit <tt/plugin_hooks.php/ before the changes will take effect. +TODO: Add a description on how to manually create the file <tt/plugin_hooks.php/, i.e. without using the Perl script. Perl is not a requisite. + <sect1>The starting point <sect2>Plugin initialization<label id="plugin_setup_file"> <p> @@ -1283,16 +1285,16 @@ <label id="plugin_init_example"><tscreen><verb> /** - * Register this plugin with SquirrelMail - * - */ + * Register this plugin with SquirrelMail + * + */ function squirrelmail_plugin_init_demo() { global $squirrelmail_plugin_hooks; $squirrelmail_plugin_hooks['optpage_register_block']['demo'] - = 'plugin_demo_options'; + = 'plugin_demo_options'; $squirrelmail_plugin_hooks['login_cookie']['demo'] - = 'plugin_demo_login'; + = 'plugin_demo_login'; } </verb></tscreen> @@ -1310,10 +1312,10 @@ <tscreen><verb> /** - * Add link to the Demo options page on the SquirrelMail - * main options page listing - * - */ + * Add link to the Demo options page on the SquirrelMail + * main options page listing + * + */ function plugin_demo_options() { include_once(SM_PATH . 'plugins/demo/functions.php'); plugin_demo_options_do(); @@ -1330,7 +1332,7 @@ <sect1>Hooks <p> In the example <ref id="plugin_init_example" name="above">, the "demo" plugin -uses two "hooks" called "optpage_register_block" and "login_cookie". Which +uses two "hooks" called "optpage_register_block" and "login_cookie". Which hooks a plugin uses depends on what kind of functionality is being implemented - where in the SquirrelMail source code does the plugin need to execute its own code? @@ -1344,13 +1346,13 @@ take return values, all depending on the type of hook being called and the context in which it is being used. On the source side (where the hook call originates), all hooks have at least one parameter, which is the name of the -hook. After that, things get complicated (sometimes). +hook. After that, things (sometimes) get complicated. <sect2>Hook types, parameters and return values <p> The design of each of the hook types has changed somewhat starting with SquirrelMail version 1.5.2, so we provide a description of the hook types for -both the 1.4 release series and versions starting with 1.5.2. Despite the +both the 1.4 release series and versions starting with 1.5.2. Despite the differences noted here, in most cases, plugins will run on the same hook without the need for version-specific code in either environment (however, there are other differences that do require version-specific code, which are @@ -1369,7 +1371,7 @@ to the <tt/do_hook/ call is what is passed along to the plugins). There is a second parameter given to plugins, but it is not normally used: it is the current value of the ultimate hook return value. All plugins are responsible -for sharing the creation/modification of whatever <tt/do_hook/ returns. The +for sharing the creation/modification of whatever <tt/do_hook/ returns. The ultimate return value is whatever the <it/last/ plugin returns from its hook implementation, but if it does return something, it should be sure to check if there was already a return value created by other plugins, which is what is @@ -1442,7 +1444,7 @@ sent to the client browser (you'll have to look at its use in context to understand how you should return values here). The parameters that your hook function gets will be anything you see <it/after/ the hook name in the actual -hook call in the source. These cannot be changed in the same way that the +hook call in the source. These cannot be changed in the same way that the <tt/do_hook()/ parameters can be. Read more about the <tt/do_hook_function()/ function in the @@ -1638,13 +1640,13 @@ <tscreen><verb> [0] = An array of links for actions (see below) (alterable). [1] = The message index of the first message on the message list page within - which the current message is found (startMessage). Can be used herein + which the current message is found (startMessage). Can be used herein for building URLs that point to the correct message list page. -[2] = The ID of the current message (id). Can be used herein to build URLs +[2] = The ID of the current message (id). Can be used herein to build URLs that point to the correct message. -[3] = The mailbox name, encoded with urlencode() (urlMailbox). Can be used +[3] = The mailbox name, encoded with urlencode() (urlMailbox). Can be used herein to build URLs that point to the correct message list page. -[4] = The entity ID of the attachment inside the mail message (ent). Can +[4] = The entity ID of the attachment inside the mail message (ent). Can be used herein to build URLs that point to the correct attachment. [5] = The default URL to go to when the filename is clicked upon (alterable, but only one URL is allowed, thus, the last plugin to execute for @@ -1652,7 +1654,7 @@ new action to array element 1 above). [6] = The filename that is displayed for the attachment. [7] = The "where" criteria that was used to find the current message (where) - (only applicable when the message was in fact found using a search). + (only applicable when the message was in fact found using a search). Can be used herein to build URLs that point to the correct message list page. [8] = The "what" criteria that was used to find the current message (what) @@ -1683,7 +1685,7 @@ specific rule available for that type. There is also an "attachment */*" hook for plugins that want to handle any -and all attachments, regardless of their mime types. Please use conservatively. +and all attachments, regardless of their mime types. Please use conservatively. Putting all this together, the <tt/demo_handle_zip_attachment()/ function should look like this (note how the argument is being passed): @@ -2033,9 +2035,9 @@ <tag><tt/extra_attributes/</tag> This is where you may add any additional JavaScript or other attributes to the -preference element. The value of this setting should be an array, where the +preference element. The value of this setting should be an array, where the keys of the array are the attribute names as you expect them to show up in the -resulting HTML, and the values are the corresponding attribute values. For +resulting HTML, and the values are the corresponding attribute values. For example, you could add an "onchange" JavaScript handler to a drop-down list: <tscreen><verb> @@ -2245,7 +2247,7 @@ <p> There are a few places in a plugin, such as when hooking into the "menuline" or "optpage_register_block" hooks, where you can provide a link to a file that is -called directly by the client browser. No matter what that page does, it should +called directly by the client browser. No matter what that page does, it should always validate that the calling client has a current login session. Thus, all such pages should start with the following code: @@ -2362,10 +2364,10 @@ <tt/rpc/|List of RPC commands that this plugin answers to|A two-element array keyed by "commands" and "errors". Each of these contains a sub-array. The "commands" array is keyed by RPC command name, where corresponding values are the English explanations for what each command does. The "errors" array is keyed by each possible error number that the plugin's RPC interface might produce, where corresponding values are English explanations of what each error number means. <tt/array("commands" => array("demo_get_one_prediction" => "Peer into the crystal ball once"), "errors" => array(720 => "demo_get_one_prediction failed"),)/@ <tt/other_requirements/|Some other non-SquirrelMail or non-PHP requirements|<tt/"Courier Maildrop LDA"/@ <tt/external_project_uri/|Address of the project page or source code repository for the plugin|<tt>"http://example.org/my_plugin"</tt>@ -<tt/per_version_requirements/|List of requirements this plugin has that are different based on the SquirrelMail version being used|An array which is keyed by SquirrelMail version numbers. Any version numbers skipped receive the same requirements laid out for the last version number that is listed below the skipped one. Each value is then a sub-array that may contain any of the requirement entries listed here, such as <tt/requires_source_patch/, <tt/required_plugins/, etc., or a special constant called <tt/SQ_INCOMPATIBLE/ (set the associated value to boolean <tt/1/), which indicates that the plugin is not compatible with the corresponding version of SquirrelMail. <tt/SQ_INCOMPATIBLE/ may also replace the entire sub-array for the incompatible SquirrelMail version, which is easier to understand. See below for an example. +<tt/per_version_requirements/|List of requirements this plugin has that are different based on the SquirrelMail version being used|An array which is keyed by SquirrelMail version numbers. Any version numbers skipped receive the same requirements laid out for the last version number that is listed below the skipped one. Each value is then a sub-array that may contain any of the requirement entries listed here, such as <tt/requires_source_patch/, <tt/required_plugins/, etc., or a special constant called <tt/SQ_INCOMPATIBLE/ (set the associated value to boolean <tt/1/), which indicates that the plugin is not compatible with the corresponding version of SquirrelMail. <tt/SQ_INCOMPATIBLE/ may also replace the entire sub-array for the incompatible SquirrelMail version, which is easier to understand. See below for an example. </tabular> -A typical implementation of this function is as follows. Note that +A typical implementation of this function is as follows. Note that this example shows a conditional requirement for the Compatibility plugin that is due to the (required) use of <tt/sq_change_text_domain()/ [FIXME: PROVIDE LINK FOR THE FOLLOWING] @@ -2432,11 +2434,10 @@ <tscreen><verb> /** - * Returns version info about this plugin - * - */ -function demo_version() -{ + * Returns version info about this plugin + * + */ +function demo_version() { $info = demo_info(); return $info['version']; } @@ -2471,7 +2472,7 @@ <sect2>Storing sensitive data <p> If a plugin needs to store sensitive user configuration files or other such data, -please consider extra steps to secure such files. One very easy way to do so is +please consider extra steps to secure such files. One very easy way to do so is to wrap all configuration files in PHP tags (and C-style block comments if the configuration data is not PHP code itself): @@ -2493,9 +2494,9 @@ needs to be protected and (hopefully) have made sure that it has been. Never store unsecured configuration data that contains any user or system-specific -information in your plugin directory. Even the above suggestions +information in your plugin directory. Even the above suggestions may not be sufficient depending on how sensitive the data is that you are -storing. In such a situation, you might think about a more complex encryption +storing. In such a situation, you might think about a more complex encryption scheme such as the one provided by the <bf/vadmin/ plugin. Note that just shipping unsecured configuration files along with a @@ -2553,11 +2554,11 @@ name="development"> API documentation. Finally, there is a plugin called "Compatibility" that is intended to solve -this problem without requiring any special coding on the part of plugin authors. +this problem without requiring any special coding on the part of plugin authors. Authors can develop one version of their plugin and seamlessly support any -SquirrelMail version. Plugin code is typically developed against the newest +SquirrelMail version. Plugin code is typically developed against the newest SquirrelMail release, and users running older versions of SquirrelMail can -use said plugin as long as they also have the "Compatibility" plugin. For +use said plugin as long as they also have the "Compatibility" plugin. For more inforamtion, please download "Compatibility" and read its README file. <sect1>Documentation files @@ -2643,7 +2644,7 @@ <sect1>Additional Resources <p> In addition to this document, help writing plugins is easily obtained by posting -to the <url url="http://www.squirrelmail.org/docs/admin/admin-12.html#ss12.3" +to the <url url="http://squirrelmail.org/docs/admin/admin-12.html#mailinglists" name="SquirrelMail plugins mailing list">. <sect1>How to release your plugin This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <jer...@us...> - 2009-04-09 15:06:08
|
Revision: 13535 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13535&view=rev Author: jervfors Date: 2009-04-09 15:05:59 +0000 (Thu, 09 Apr 2009) Log Message: ----------- Minor changes in formatting. Replacing a working mail address with an example. Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2009-04-09 14:36:01 UTC (rev 13534) +++ trunk/documentation/devel/devel.sgml 2009-04-09 15:05:59 UTC (rev 13535) @@ -1286,7 +1286,6 @@ <label id="plugin_init_example"><tscreen><verb> /** * Register this plugin with SquirrelMail - * */ function squirrelmail_plugin_init_demo() { global $squirrelmail_plugin_hooks; @@ -1314,7 +1313,6 @@ /** * Add link to the Demo options page on the SquirrelMail * main options page listing - * */ function plugin_demo_options() { include_once(SM_PATH . 'plugins/demo/functions.php'); @@ -2376,50 +2374,48 @@ <tscreen><verb> /** - * Returns info about this plugin - * - */ -function demo_info() -{ + * Returns info about this plugin + */ +function demo_info() { return array( - 'english_name' => 'Demo Future Prediction', - 'authors' => array( + 'english_name' => 'Demo Future Prediction', + 'authors' => array( 'Emma Goldman' => array( - 'email' => 'em...@st...', - 'sm_site_username' => 'emma', + 'email' => 'em...@ex...', + 'sm_site_username' => 'emma', ), - ), - 'summary' => 'Adds important information above the folder list.', - 'details' => 'This plugin automatically sees into the user\'s ' - . 'future and places important details about upcoming ' - . 'events above the folder list.', - 'version' => '2.5.1', - 'required_sm_version' => '1.2.9', - 'requires_configuration' => 0, - 'requires_source_patch' => 0, - 'per_version_requirements' => array( + ), + 'summary' => 'Adds important information above the folder list.', + 'details' => 'This plugin automatically sees into the user\'s ' + . 'future and places important details about upcoming ' + . 'events above the folder list.', + 'version' => '2.5.1', + 'required_sm_version' => '1.2.9', + 'requires_configuration' => 0, + 'requires_source_patch' => 0, + 'per_version_requirements' => array( '1.5.2' => array( - 'required_plugins' => array(), + 'required_plugins' => array(), ), '1.5.0' => array( - 'required_plugins' => array( - 'compatibility' => array( - 'version' => '2.0.7', - 'activate' => FALSE, - ) - ) + 'required_plugins' => array( + 'compatibility' => array( + 'version' => '2.0.7', + 'activate' => FALSE, + ) + ) ), '1.4.10' => array( - 'required_plugins' => array(), + 'required_plugins' => array(), ), '1.2.9' => array( - 'required_plugins' => array( - 'compatibility' => array( - 'version' => '2.0.7', - 'activate' => FALSE, - ) - ) + 'required_plugins' => array( + 'compatibility' => array( + 'version' => '2.0.7', + 'activate' => FALSE, + ) + ) ), ), ); @@ -2435,7 +2431,6 @@ <tscreen><verb> /** * Returns version info about this plugin - * */ function demo_version() { $info = demo_info(); This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <pdo...@us...> - 2009-04-14 09:24:05
|
Revision: 13538 http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13538&view=rev Author: pdontthink Date: 2009-04-14 09:23:59 +0000 (Tue, 14 Apr 2009) Log Message: ----------- Add another plugin example Modified Paths: -------------- trunk/documentation/devel/devel.sgml Modified: trunk/documentation/devel/devel.sgml =================================================================== --- trunk/documentation/devel/devel.sgml 2009-04-13 16:52:57 UTC (rev 13537) +++ trunk/documentation/devel/devel.sgml 2009-04-14 09:23:59 UTC (rev 13538) @@ -1208,9 +1208,10 @@ <p> The plugin architecture of SquirrelMail is designed to make it possible to add new features without having to patch SquirrelMail itself. Functionality like -changing user passwords, displaying ads, and calendars should be possible to add -as plugins. In this scheme, either package (SquirrelMail or a plugin) may be -upgraded independently without risk of one breaking the other. +changing user passwords, displaying ads or calendars, and managing spam +settings should be possible to add as plugins. In this scheme, either package +(SquirrelMail or a plugin) may be upgraded independently without risk of one +breaking the other. <sect2>The idea <p> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |