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

Robert P. J. Day rpjday
Mon Oct 18 05:57:38 CDT 2004


  ... and why i find it overwhelmingly confusing.  i'll make this
post explaining why i find the customization sequence (CS) both
confusing and unnecessarily complicated, then i'll shut up about it.

  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.

  in the case of pmwiki 2, it would normally mean that the default
settings would come from pmwiki.php, after which the user would make
some changes/overrides at the overall level (local/config.php?), then
at the group level with per-group settings, and finally at the
per-page settings.  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".  so a
reasonable CS might be represented by:

  pmwiki.php		# supplied overall settings
  local/config.php	# user-supplied override overall settings
  per-group settings	# user-supplied per-group settings
  per-page settings	# user-supplied per-page settings

and i'm going to suggest that this is how newbies might initially
assume that things work.  but that's not the case.  in fact, far from
it.

  first, it's true that pmwiki.php starts things off, so that's fine.
but consider the contents of that file in terms of the CS:

pmwiki.php
----------
=====
  @include_once('scripts/version.php');
=====

no problem there, that's a pretty trivial inclusion to get the package
version.  further down, we have:

=====
  if (file_exists("$FarmD/local/farmconfig.php"))
    include_once("$FarmD/local/farmconfig.php");
  if (file_exists('local/config.php'))
    include_once('local/config.php');
=====

ok, again, that looks all right, and it would normally suggest that
the user can start overriding settings, first at the farm level, then
at the local config level, where the latter settings would take
precedence.  so far, so good.  but then things get confusing:

=====
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.  this has the potential to lead to *massive*
confusion, as the user won't understand why some specific settings he
entered in the local config.php file are being ignored.  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.  but
it gets even more confusing.

  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.

  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.  turning this into what is
effectively a two-level selection (EnableStdConfig, then getting more
specific with individual variables) just makes this more cumbersome
and i don't see the benefit.

  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.

  first, there is no distinction between the two levels of
customization.  the file scripts/stdconfig.php appears to recognize a
single variable -- EnablePerGroupCust -- which doesn't say anything
about per-*page* customization, or a general hierarchical
customization at all.  the variable name is certainly at least a
little misleading, and might be better named as i suggested before --
EnableHierCust or something similar -- which will work with arbitrary
levels in the future.  but it gets more 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).  i don't see why this should be the case.  if, as a user, i want
hierarchical customization, i should be able to get it by just setting
the appropriate variable in my local/config.php and be done with it.
instead, i have to deal with stdconfig.php, possibly having to turn
off the features i *don't* want.  again, it's the incovenience of that
two-level CS involving stdconfig.php that gets in the way.  but that's
still not the worst of it.

  if you take a look at how per-page and per-group customizations
are actually done in scripts/pgcust.php, this is also thoroughly
counter-intuitive.  as i read it (and not being a PHP expert, i might
be completely wrong), the PHP program pgcust.php will work its way
from the most specific customization (per-page) up to the most general
(per-group), and will take the first one it finds and stop there.
this is most *definitely* not what most users will expect.

  the standard CS is to go from most general to most specific and
*accumulate* the changes, where more specific settings get the chance
to override more general settings, but you consult them *all*.  i
remember patrick's rationale that doing it this way gives one more
flexibility but, after i thought about it for a while, i don't buy
this argument.  quite simple, if i put a page in a group, and i create
some per-group cust. settings, those settings should apply to that
page unless i specifically override them with per-page settings.  if i
didn't want per-group settings to apply to a page, then i shouldn't
have put that page in that group.  that's what most users will expect
to see and, if it works differently, i guarantee they'll get confused.

  and, finally, at the bottom of pgcust.php, i think the consultation
of local/default.php is out of place.  overall defaults should have
been set much earlier in local/config.php, not here, since this once
again violates the normal sequence of most general to most specific
settings.

  anyway, that's just my rantings.  feel free to comment on them,
criticize them or just plain ignore them.

rday

p.s.  just to muck things up even further, i don't think the settings
for DefaultGroup or DefaultName should have anything to do with
customization settings.  those variables might be useful for what
group and page are initially *displayed* when you browse the wiki, but
i don't think they should have anything to do with the CS.

p.p.s.  and, as i said in an earlier posting, i'm concerned with the
choice of potentially-misleading variable names.  specifically, i'm
thrown by the choice of "Group" to refer generally to a group name (a
good choice) versus the choice of "Name" to refer to a page name (a
bad choice).

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

to allow for future extension to multiple group levels, i suggest
distinguishing between a page's full name and it basename by actually
incorporating something like "Base" into the name, or "Full" to go the
other way, depending on what you want as the default.  above all,
referring to the current page name with the variable "$Name" is just a
recipe for confusion.




More information about the pmwiki-users mailing list