[pmwiki-users] Feature request: Action lists in skins

Thu Apr 7 11:58:20 CDT 2005

On Thu, Apr 07, 2005 at 05:12:38PM +0200, Joachim Durchholz wrote:
> Patrick R. Michaud wrote:
> 
> >On Thu, Apr 07, 2005 at 10:48:43AM +0200, Joachim Durchholz wrote:
> >
> >>I simply don't get it. What the heck is complicated about
> >>
> >> <!--ActionList-->
> >
> >To a skin designer who simply wants to display the actions (and assumes
> >that they're set properly), I agree this is not complicated.  But for a 
> >wiki admin who wants to change the set of actions that appear at this 
> >point,
> >it's not at all obvious where they're stored or how to do it.  [...]
> 
> I don't think that the wiki admin will deal directly with that part of 
> the skin, at least not directly.
> [...]
> >What <!--function:ActionList--> does do is add another place to have
> >to look for the link information; i.e., complexity has gone up.
> 
> Only if the skin designer wants to interfere with the order of the 
> actions, or their selection.

See http://pmichaud.com/pipermail/pmwiki-users/2005-April/012162.html .
It illustrates perfectly what I'm describing.  (And I suspect that
the reason why this sort of question isn't asked more often is because
the current system makes the answer sufficiently clear to wikiadmins.)

> >Consider our two examples:
> >[...]
> >Remembering that a skin designer already must know about HTML and 
> >$-substitutions to work with other parts of skin, which of the 
> >above is more straightforward (obvious) for achieving:
> >   - change the sequence in which actions are displayed
> >   - remove the "Page History Link"
> >   - add an "Upload" link
> >   - add a link to a non-wiki page
> 
> None of these are a skin designer's business.

Touche'.

> The first three are the domain of the wiki administrator. If you force 
> the wiki admin into editing the skin, he'll have to learn the skin 
> syntax along with HTML, CSS, and PHP. It's forcing him up the learning 
> curve, at a time when his mind is on functionality, not design.

Wiki administrators generally already know a little HTML, otherwise
they wouldn't even be interested in this stuff.  Often they're coming
from a pure-HTML environment and looking at PmWiki as a way to
get around HTML's limitations.  And claiming that the existence of 
$-substitutions means that someone must learn PHP syntax is a 
real exaggeration, and I wish you'd stop making that particular stretch.
Someone looking at

    <a href='$PageUrl?action=edit'>

can generally figure out what $PageUrl is doing without having to know an 
ounce of PHP or crack open a PHP manual.

> Maybe it's better to set the action array up as a 
> simple list of HTML à la
> 
>   $ActionList = array (
>     '<a href="$PageUrl?action=edit">$[Edit Page]"</a>',
>     '<a href="$PageUrl?action=print" target="_blank">
>                                     $[Printable View]"</a>',
>     ...
>   );

Sure, in which case this is basically the same as

    $ActionListFmt = 
      '<a href="$PageUrl?action=edit">$[Edit Page]"</a>
       <a href="$PageUrl?action=print" target="_blank">$[Printable View]"</a>
       ...
      ';

which was my previous proposal.

> >    - change the separator between the links
> 
> That's covered. Either as
> 
>   <!--function:ActionSeparator * -->
>   <!--function:ActionList-->
> 
> or as
> 
>   <!--function:ActionList separator=*-->

No, now you misread what *I* wrote.  My original question was
"[which] is more straightforward (obvious) for achieving" the
result, not whether you could do it.  Someone who sees the HTML
knows instantly how he or she can change the separator between
the links, someone who sees only 
has to find and read the documentation for the ActionList function
before he/she can do it.

> It's the wrong target audience. Skin designers don't (well, shouldn't) 
> care what goes into the action lists. 

Sure they care, or at least have some rudimentary idea of it.  I don't 
know any skin designer who is not also a wiki admin.

> >Wiki admins are usually neither
> >skin designers (i.e., creating skins for others to use) nor recipe 
> >writers, but just want to get a wiki running and customized to appear how 
> >they
> >want it.
> 
> Agreed.  But these need to know enough about PHP to set up config.php.

Yeah, but all that a wiki admin needs to know to set up config.php
is to be able to set a few variables, and perhaps an include() statement.
In this sense config.php is little different from any other configuration
file syntax (e.g., Apache) -- in fact, many wiki admins don't even 
realize that what appears in the config.php file is in fact PHP code --
they just think of it as setting lots of variables.  Yes, a wiki admin
*can* put lots of PHP-specific code into config.php, but knowing PHP
syntax certainly isn't a requirement for setting up config.php, and
it's not safe to assume that wiki admins are comfortable with anything
more there than setting variables.

> In the vast majority of the cases, i.e. if the various recipes and the 
> standard configuration "do the right thing", there's no need to ever 
> touch the actionlist machinery for them.

Trust me on this one -- the "vast majority" you refer to here is mythical.  
In reality there are about four or five equal-sized groups which have 
very different ideas about what constitutes "the right thing".  
(And often each group thinks it's the majority group, and can't see 
why anyone else would consider any other possibility.)  The differences
often depend on application (CMS, blog, wiki, web publishing, forum) and 
intended authoring audience (personal site, development group, 
organizational intranet, organizational web site, public collaboration).  
There is no "right thing" that meets all these needs, and the wiki 
admin is the one who needs the power and ability to easily select 
and configure appropriately.  Recipe designers can make good guesses,
but the guess is bound to be wrong for a significant portion of
users.

> > And as a group wiki admins are far less comfortable with PHP than
> >with HTML/CSS.  By moving the action list out of the skin and 
> >into a structured PHP array, we're moving farther away from the world
> >that most wiki admins live in (HTML), and we're removing control of the
> >output from the audience that needs and demands it most.
> 
> Do they indeed need that control?

I again point to the pmwiki-users message I mentioned earlier.  
Indeed, I believe that the reason that people adopt PmWiki is because
it gives them that control at a level that is accessible to them.

> When settin up my wikis, the one thing that I wanted was the standard 
> set of actions, plus any actions included via recipes.

Which recipes?

> Then I met the beeblebrox-gila2 template. It had a "read" action. Huh?? 
> It also had a bewildering array of additional action; some of them I 
> liked and would have wanted them in the other skins (particularly in the 
> phase when I was trying out several skins to see which worked best for 
> me); some of them couldn't have been lest interesting to me so I had to 
> remove them.

I think you've just proved my point -- you didn't want an action 
that someone else thought was important.  A skin designer will believe
one thing, a recipe designer another, and the wiki admin yet another.
Unfortunately, the wiki admin has to be given the final say, and is
generally the least experienced of the three.

> I would have thought that checking all the skins would have been a 
> simple matter of downloading them, then in turn configuring PmWiki to 
> use that skin and try it out. 

I know I'm being a bit dense here (sorry), but what part about this 
wasn't simple?  Was it that you had to go and find/change the available
actions in each skin?  (And I'm still lost as to which actions were
being added by recipes -- maybe I just haven't been keeping up with 
the recipes lately.)

And wouldn't the $ActionSkinsFmt variable I proposed have been
sufficient?

> [...] but the above report should convince 
> anybody that the current state of action handling in skins leaves many 
> things to be desired.

Sure, no argument there.  Lots of things about PmWiki (Apache, HTML,
CSS, Linux, Windows) leave many things to be desired.  But that doesn't
mean the long term, good solutions are always easy to come by.

> I'm not yet convinced see that the wikipage approach solves the issues. 
> It nicely decouples the action list from the skins, but it still burdens 
> the administrator with writing the actions down. If the admin mistypes 
> something, he'll get into trouble (he may even lose all actions and not 
> know how to get back into the edit page - if he's new, he may not know 
> that simply adding ?action=edit will get him the edit page no matter 
> what the action list is).

With apologies,

    "I'm not yet convinced that the <!--function:ActionPage--> approach
    solves the issues.  It nicely decouples the action list from the skins,
    but it still burdens the administrator with finding the available
    array entries and figuring out what to set to change them.  If
    the admin mistypes something, he'll get into trouble (he may even
    cause the entire PHP script itself to stop working -- if he's new,
    he may not know that everything has stopped working because he left
    out a quotation mark or comma in his array entry)."

(If you don't think that admins get confused by a missing semicolon
or punctuation, I have lots of stories to share.  Especially among
wiki admins who are in fact 20-year unix administrators with experience
in PHP, Python, Perl, etc. but couldn't find the missing semicolon
that caused their site to totally stop working.)

> Why should the wiki admin bother with 
> these clerical tasks? He has selected the recipe that implements that 
> ?action=foo, then why doesn't the recipe also install the item in the 
> action list?

Because the wiki admin might not want the link for the action to appear
in his skin, even though the action is available.  Just because an
admin does include_once('scripts/refcount.php') or 
include_once('scripts/rss.php'), does that mean that PmWiki should
suddenly be displaying ?action=rss, ?action=rdf, and ?action=refcount
links?  You may say "yes", but I know I can find good-sized number of 
people who will say that recipe actions should not automatically 
appear in the action list just because they decided to enable the
feature.

> It's just that I'm at an 80% solution right now, with bits and pieces 
> hanging around. I get ample feedback on those missing 20%, but I haven't 
> gotten anything about the 80% part - yet I need the latter to do the 20%.
> What frustrates me isn't that nobody seems to agree with it instantly. 
> The situation is that I'm exploring a quite lonely part of design space, 
> and instead of helping me find a way to better places from where I am, 
> everybody insists on restarting from someplace entirely different. 
> That's frustrating for me and ineffective for both sides of the exchange.

No, don't feel persecuted here.  The situation is much more likely:
   - the vast majority of people on the list have trouble following what
     we're discussing
   - of those who can follow it, you're getting ample feedback
     about the missing 20% because they agree that the "80% solution" 
     is entirely technically feasible for what it does (and needs no
     further feedback), but won't be able to handle the remaining 
     20% of issues as well as the existing or other proposed methods.

Pm