[Pmwiki-users] thoughts on customization sequence in pmwiki 2 ...

[Patrick R. Michaud]

On Mon, Oct 18, 2004 at 07:50:23AM -0400, Robert P. J. Day wrote:
> 
>   by way of intro, almost all software i've ever seen has a universal
> and straightforward CS:  first, there are overall defaults that come
> with the package, after which the user can add some of his own
> settings, typically from most general to most specific, and that's the
> order in which the settings are consulted -- the more specific
> settings always override the more general ones.  this is, by all
> accounts, a universal CS and one does not normally deviate from it
> without some *really* compelling reasons.

There *are* some compelling reasons:
1.  Ease -- With many things in PmWiki, setting values is much easier 
    than unsetting, resetting, or undoing their effects.  This is especially
    true for things like author tracking, uploads, markup, etc.
    PmWiki could go ahead and configure items like these before local
    customization, but undoing their effects is a lot more work
    than simply specifying you don't want them in the first place.
    It's also prone to error -- if a future version of PmWiki changes
    the way in which something works, then the local settings to 
    "undo" something may no longer function.
2.  Efficiency -- "Set then unset" is a lot less efficient than "never set".
3.  Flexibility -- The current organization preserves maximum flexibility to
    the administrator.  If someone wants to load all of the standard 
    settings before doing any other customization, it can be easily done by
                include_once('scripts/stdconfig.php');
    in the local.php.  But the reverse isn't true--if PmWiki sets all of
    its defaults before calling the local customization file, there's no
    way for the local customization to say "hey, don't load this default
    module".
    
> and note that this would normally represent the
> order of customization, as later settings override earlier ones, and
> the end result is a *cumulative* effect, not "instead of".  

Note that I've already indicated in a previous message that I'm going to 
switch per-page and per-group customizations to be cumulative instead 
of exclusive.

> =====
> if (IsEnabled($EnableStdConfig,1))
>   include_once("$FarmD/scripts/stdconfig.php");
> =====
> 
>   if the user sets $EnableStdConfig (in local/config.php, i'm
> assuming), this opens up the possibility of *overriding* specific
> settings in local/config.php with what one finds in
> scripts/stdconfig.php.  

Actually, the "1" at the end means that $EnableStdConfig is assumed
to be set *unless* the adminstrator has set it to zero in local/config.php--
i.e., you'll get the standard configuration unless you explicitly
request otherwise.  And if one does $EnableStdConfig=0, they're basically
saying to PmWiki "don't load anything by default--I want to control the
entire configuration process."  This can make for a very streamlined
script, or allow someone to massively customize PmWiki.

Secondly, the scripts loaded by stdconfig.php are carefully created so
that they never override a local/config.php setting.  This is the purpose
of all of those SDV(...) calls in the scripts--it means "set default value", 
or "set a value if one has not already been set".

> it would seem
> to make *far* more sense to have the standard config settings pulled
> in *first*, then allow the user to start overriding any of that.  

Except that overriding is expensive, prone to error, and difficult to
do.  If it helps, think of stdconfig.php as being "okay, now load the
appropriate modules and values based on the administrator's configuration 
settings" rather than "set PmWiki's defaults".

>   the stdconfig.php file consists mostly of a number of conditional
> includes.  this means that, if the user wants the effect of, say,
> *most* of them and wants to get that effect conveniently, he would
> first set to zero the variables corresponding to what he *doesn't*
> want, then set $EnableStdConfig to pull in stdconfig.php to get the
> effect of the rest of them.  i doubt any newbie user would have
> guessed that that's what he should have done -- it's not at all
> intuitive.

Well, you'd be wrong here.  First, by default $EnableStdConfig already
pulls in stdconfig.php automatically--it exists to allow an administrator
to say "*don't* load the standard configuration".  Second, in my experience
newbie wiki administrators have very little problem with the idea of setting
flags to turn features on and off--that's a very common configuration
concept.  

>   frankly, it would seem more intuitive for pmwiki.php to simply pull
> in *everything* in this directory, or let the user select what he
> wants or doesn't want individually.  

I'll argue that this is exactly what PmWiki does.  

First, there's a problem with "simply pull in everything", in that 
there are dependencies between modules that require them to be loaded 
in a specific sequence.  For example, the print.php module has to
be loaded before tlayout.php, which really needs to be loaded before
any other customization script takes place.  Thus, it's no good to just 
load every file in scripts/ in random order--a sequence has to be specified,
and this is what stdconfig.php does.

Second, setting $Enable... variables to 1 or 0 is exactly "let the user 
select what he wants or doesn't want individually".  

>   finally, the per-group and per-page CS is massively non-intuitive.
> in general, having overall defaults, then allowing per-group, then
> per-page settings is an excellent idea.  but the way they're
> implemented here is hopelessly confusing.

I'll accept that it might be confusing for some, but the existence of a few
hundred PmWiki sites that make use of it would indicate that it's not 
*hopelessly* confusing.  :-)

>   even if one sets this variable in local/config.php, it won't do any
> good unless they *also* set EnableStdConfig (at least, the way i read
> it).  

Alas, you've read that wrong and made a large number of mistaken
conclusions from that.  Rather than refute all of those conclusions
individually, I'll just let you re-examine things with this new
information and see if you still have concerns.

> unless all these names have been absolutely cast in stone (and they
> may very well be), i *implore* you to change them to more meaningful
> and relevant names.  as options, the current group and page name might
> be represented by
>   $CurrentGroup
>   $CurrentPage

These are too long--variables that are used frequently (and $Group and
$Name are by far the most commonly used items in templates) should
be short and easy to remember.  Also, $CurrentPage itself would be 
confusing -- does it refer to just the name component of the page or 
the page's full name?  I'm very likely to leave $Name and $Group as
they are, although I might switch to $FullPageName instead of $PageName.

Pm