[Pmwiki-users] skins

[Patrick R. Michaud]

On Sun, Oct 24, 2004 at 05:34:06PM +0200, Knut Alboldt wrote:
> At 08:57 23.10.2004, Pm wrote:
> >Actually, after thinking about this a bit more (and helping a couple of
> >other users troubleshoot layouts) I've decided to try out a naming
> >standard for skins in the pub/skins/ directory.
> 
> Glad to read this !

Well, don't celebrate just yet.  After trying to write the documentation
for the new system, I'm not so sure it's a good idea.  So, I need some 
help and advice here from the group about how the system should work, and 
how to document it so that new wiki administrators can easily figure out
what's going on.

First, let's start with some declarations of what I'm trying to 
accomplish (requirements R1-R3):

R1: When a new wiki administrator installs PmWiki for the first time,
    it should "just work", and it should look very similar to what they've
    seen on the pmwiki.org site.

R2: The administrator should then be able to customize the skin for
    his/her site.  There are several levels or types of customizations,
    with increasing levels of difficulty for each:
       a.  Change the logo in the upper-right corner (should be trivial)
       b.  Download and install a skin from the cookbook
       c.  Change the CSS colors/styling of a skin
       d.  Make simple changes to the layout of a skin
       e.  Make a new customized skin
       f.  Make a custom skin organized for publication in the cookbook

R3: PmWiki's default skin configuration needs to be accessible enough to 
    new administrators that they can look at them and begin to get some 
    idea of how to make changes and modifications to get what is desired.  

R4: Skin modifications should be preserved across upgrades.

Okay, here are the various problems I'm running into.  I'll start with
PmWiki 1's mechanism of using $PageTemplateFmt to identify the file
containing the skin layout, then I'll get into the issues with $PageSkinFmt.

Issues with $PageTemplateFmt (PmWiki 1)
---------------------------------------

When first installed, PmWiki uses the following files for its skin:
    pub/skins/pmwiki/pmwiki.tmpl   (default value of $PageTemplateFmt)
    pub/skins/pmwiki/pmwiki.css    (specified by the pmwiki.tmpl file as
                                   $PubDirUrl/skins/pmwiki/pmwiki.css)

P1: If an administrator modifies the default skin files "in place", then 
    those modifications may be overwritten/lost when the administrator 
    upgrades PmWiki.  

To avoid this problem, the default files contain various admonitions 
to make copies of the files before modifying them, and to change the
configuration variables to point to the copies.  Which leads us to:

P2: $PageTemplateFmt must specify a file path on disk, but many 
    administrators misread the instructions and try to set it to
    the URL-location of the template file, then cannot figure out
    why it's not working properly.

P3: To make modifications to pmwiki.css, one must copy the pmwiki.css
    file and then change the location in whichever template file is
    currently being used.

P4: If the administrator simply copies the entire pub/skins/pmwiki
    directory to a new skin directory (e.g., pub/skins/myskin) and
    sets $PageTemplateFmt='pub/skins/myskin/pmwiki.tmpl', they're
    often surprised when their modifications to pub/skins/myskin/pmwiki.css
    seem to have no effect (because the copied pmwiki.tmpl is still 
    pointing to the original pmwiki.css in skins/pmwiki).

P5: Things become even more complex when dealing with WikiFarms and
    farm-shared templates.


The $PageSkinFmt approach (PmWiki 2.0.devel16)
----------------------------------------------

To try to get around some of the above problems, in 2.0.devel16 I
introduced $PageSkinFmt, which identifies a directory in pub/skins/
instead of a specific template file.  PmWiki then looks for a file
named "screen.tmpl" in the skin directory to use as the template file,
and sets $SkinDirUrl to the associated URL for the skin's directory
(relative to $PubDirUrl).

While at first this looks like a substantial improvement, it still can
leave a lot of confusion for a new administrator who isn't familiar
with the layout:

Q1: The problem still exists that an administrator cannot modify files
    "in place" but must make a copy.

Q2: Worse, instead of copying a simple file to make modifications, the 
    administrator must now copy an entire directory.  More to the point, 
    the administrator must know *how* to make a copy of the directory,
    put it in the correct location (pub/skins/myskin), and set $PageSkinFmt
    to the correct name (i.e., without the 'pub/skins/' prefix).
    
    Note that many people who know how to copy individual files can get
    easily stumped when it comes to copying directories, especially if
    they don't have shell/command line access to their server.

Q3: The variable used to specify the skin ($PageSkinFmt) doesn't seem
    to have any direct correspondence to the name of the template file
    used to control the layout (screen.tmpl).

Overall, the problem I have with this approach is that it adds complexity
and learning curve to new administrators (in terms of making sure files 
are named properly) without gaining any real benefit in terms of 
making modifications and configuration improvements easier.  (One 
possible exception is that installing cookbook skins may be somewhat 
easier in this approach.)

I really noticed this issue when trying to write the LayoutBasics
documentation--everything is okay until you get to the steps that say
"make a copy of the pub/skins/pmwiki directory" and "set $PageSkinFmt to
point to your new directory".  For example, if someone copies 
pub/skins/pmwiki to pub/skins/myskin (and a new admin may say "uhhh,
how do I do that anyway?), then sets $PageSkinFmt to 'pub/skins/myskin',
then things don't work and it's not terribly obvious why.

So, I think some other approach is needed.  A big part of the confusion
is that PmWiki has to read templates in terms of *filenames* while the
template has to specify the locations of graphic elements and CSS files
in terms of URLs, and so names that work for one don't always directly
map to the other.

Suggestions and comments very welcome.

Pm