Updates in the plugin development documentation

Commit 13252[1] introduced the following paragraphs:

"A plugin can try to be smart about where to find the needed configuration
file by doing something such as this:

    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');

This assumes that the plugin has some sensible defaults in the sample
configuration file - if the plugin must be configured specifically for the
system upon which it is installed, remove the third line in this example."

If a plugin has a general configuration that can make it work out of the
box in the most cases, I prefer to have that configuration coded into the
plugin itself. If a valid configuration file exists, the plugin will allow
this to overrule the pre-set configuration.

I don't like to have the plugin read configuration from a configuration
file with the word "sample" in the filename, even if such a file exists.
One reason is that it encourages administrators to modify
"config.sample.php" instead of "config.php" which might cause them trouble
later. Another is that some distributions might want to have
"config.sample.php" in a documentation directory (and not a code
directory) when re-distributing.

For these reasons I'd like to have the code and the describing text in the
documentation rewritten so that it doesn't suggest actual use of the file
"config.sample.php".

And correct me if I'm wrong, but "sample" should really be "example",
since that's what's it all about. A "sample" is a small part of anything
or one of a number, intended to show the quality, style, or nature of the
whole. An "example" is a pattern or model, as of something to be imitated
or avoided. Could the documentation be updated with "sample" replaced by
"example", or is the old naming convention too much rooted?

Sincerely,
Fredrik

[1]
http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/trunk/documentation/devel/devel.sgml?view=diff&r1=13251&r2=13252

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
-----
squirrelmail-devel mailing list
Posting guidelines: http://squirrelmail.org/postingguidelines
List address: squirrelmail-devel <at> lists.sourceforge.net
List archives: http://news.gmane.org/gmane.mail.squirrelmail.devel
List info (subscribe/unsubscribe/change options): https://lists.sourceforge.net/lists/listinfo/squirrelmail-devel