[pmwiki-users] pmwiki-2.2.0-beta1 released

Patrick R. Michaud pmichaud at pobox.com
Mon Sep 25 13:43:25 CDT 2006

I've just released pmwiki-2.2.0-beta1, now available from:


The big change in this version over previous versions is the
treatment of links and page variables inside of (:include:)'d
pages -- previously, all links and page variables (e.g., [[link]]
and {$Name}) were treated as relative to the currently displayed 
page, but in this version it's possible to make them relative to 
the included page.  

If you've been using the "(:includeg:)" markup provided by
some of the Cookbook recipes, then essentially we're just
making (:include:) act like (:includeg:), except that it's
being done at a more fundamental and systemwide level than
(:includeg:) is doing.

If what I'm writing here is confusing or doesn't make much sense
to you, then it's probably safe to just ignore it for now.  I'm
fairly sure it'll all make more sense (and be more natural for
everyone) in the end.  

So, at some point in the future, PmWiki will default such that
[[link]] and {$var} produce output relative to the page in which 
they are written.  Since this substantially changes the
current meaning of {$var}, we now have a new {*$var} form of 
page variable that always returns a value for "the currently
displayed page".  Thus {*$FullName} always returns the full name 
of the currently displayed page, even if it was written in the
text of another page displayed via (:include:).

The {*$var} form is primarily for use in utility pages such as
Site.PageActions and Site.EditForm, where we want to be able to
refer to "the currently displayed page" as opposed to the Site.*
pages that contain the page variable markups.  That means that
{$var} is then free to take on values of "the included page",
which seems to be what authors naturally expect.

However, because there are a lot of existing sites and pages that
may depend on the current meaning of {$var}, we'll have
a transition period where the PmWiki default will continue to be 
that {$var} is a value of the currently displayed page.  (I.e.,
{$var} is the same as {*$var}.)

This is just a temporary transition period, to give people some
breathing room to convert existing pages, recipes, and customizations
to switch any absolute {$var} to be {*$var} instead.  For most
sites there shouldn't be too many of these -- typically they occur in

    SideBar pages with ?action= links to the current page
    $GroupHeaderFmt and $GroupFooterFmt

Sites that want to see the effect of relative page vars can set

    $EnableRelativePageVars = 1;

As mentioned before, eventually this will become PmWiki's default
setting, so it's a good idea for sites to experiment with this
setting and see what may need to be converted.

If there are any sites that absolutely want to preserve the old 
"absolute" behavior for links and page variables in included files, 
it can be done with:

    $Transition['abslinks'] = 1;     # use absolute links and page variables

As always, if there are any questions or anyone runs into any
difficulties, the pmwiki-users mailing list will be glad to help.

In addition to the above changes, the (:include:) directive is
getting a bit of a makeover to feature some new options to control
relative link handling and error messages.  The big change at the 
moment is the addition of a "basepage=" option, which allows an 
author to specify the page to use for all relative links and 
page variables in the included text.  If basepage= isn't specified, 
then links and page variables are treated as relative to the 
included page itself.

An author can use basepage= to make (:include:) act like the 2.1.x
version, in which all links and page variables are relative to the
currently displayed page:

    (:include Group.SomePage basepage={*$FullName}:)

There are more changes coming soon, including page text variables
(being able to quickly grab values from another page's contents)
and an extensible (:pagelist:) command.  

Comments and questions welcomed as always.


More information about the pmwiki-users mailing list