Re: Updates in the plugin development documentation

On Sat, Aug 2, 2008 at 9:25 AM, Fredrik Jervfors
<[email protected]> wrote:
> 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.

OK, then you should do that in your plugins.  ;-)  I think this has to
be the choice of the author.  For some plugins, it's just not sensible
from a design or coding point of view to hard-code defaults.  It makes
more sense to me to use a default configuration file, which could be
called config_default.php.

> If a valid configuration file exists, the plugin will allow
> this to overrule the pre-set configuration.

Cascading configuration sets vs. just one should be the author's choice IMO.

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

On one hand, they deserve it if they can't read the installation
instructions.  On the other hand, I understand the desire to make it
easy to use for clueless admins too.  Personally, at this juncture, I
am not interested in going quite that far.  What I can do, however, is
use a config_default.php instead of config_sample.php.  I will still
include an example configuration file, though, named as you suggest
below.

> 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?

-------------------------------------------------------------------------
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: [email protected]
List archives: http://news.gmane.org/gmane.mail.squirrelmail.devel
List info (subscribe/unsubscribe/change options): https://lists.sourceforge.net/lists/listinfo/squirrelmail-devel