[pmwiki-users] PData support for pagelisting images

Patrick R. Michaud pmichaud at pobox.com
Thu Sep 7 13:51:15 CDT 2006

On Thu, Sep 07, 2006 at 10:43:04AM -0700, Martin Fick wrote:
> --- "Patrick R. Michaud" <pmichaud at pobox.com> wrote:
> > One of the things that *greatly* concerns me about
> > the {$:var} markup
> > is that authors are going to get very confused by
> > trying to put
> > page variables in the values.
> ...
> > It gets worse when we have a page called SomePage
> > with:
> > 
> >     FirstName: Patrick
> >     LastName: Michaud
> >     FullName: {$:FirstName} {$:LastName}
> > 
> > because an author using {SomePage$:FullName} is
> > going to expect the result to
> > grab the FirstName and LastName values out of
> > SomePage and not the current page.
> I think that one solution to this would be the elusive
> yet to be defined "this page" operator that has been
> discussed many times on this list with reference to 
> page variables.  If this operator were say "==", this
> dilema could be solved by this:
>      FirstName: Patrick
>      LastName: Michaud
>      FullName: {==$:FirstName} {==$:LastName}
> which no matter where it were referenced from 
> should be equivalent to:
>      FirstName: Patrick
>      LastName: Michaud
>      FullName: {SomePage$:FirstName} {SomePage$:LastName}

I've been wondering if this goes the wrong way, and how
much it would hurt existing sites to change things around 
at this point (possibly as a 2.2.0 release, if we do it).

The fact that {$Name} always refers to the currently
browsed page and [[OtherPage]] always refers to a page
in the currently browsed group has long been a tricky/
unintuitive point for authors, including somewhat experienced 

For example, suppose we have a page called OtherGroup.XYZ,
and it contains the markup

    My name is {$Name}, and I can be found [[here]].

Further, let's have a page called Main.ABC do

    (:include OtherGroup.XYZ:)

As PmWiki is written now, it does a straight text substitution, 
so that {$Name} and [[here]] are evaluated in the context of
the including page.  Thus {$Name} becomes 'ABC' and [[here]]
is a link to Main.Here, even though they originally came
from OtherGroup.XYZ .  I know this catches a lot of people
off-guard, because they expect {$Name} and [[here]] to
always be related to the page in which they're written, as opposed
to the one in which they're included.

So, how much pain would we cause by switching this around now?  
If we fixed it so that {$Name} and [[link]] were always treated
as being relative to the page in which they are written, 
we could introduce another form to refer to the currently
browsed page.  Something like {==$Name}, or perhaps {*$Name}
or {.$Name}.  

Then, an author who really wants to refer to the name and
pages of the including page would write

   My name is {.$Name}, and I can be found [[{.$Group}/here]].

to get the name and group of the currently browsed page.

I'm thinking, perhaps unrealistically, that this wouldn't
cause too much if any pain for existing sites.  It really 
only affects things where include-like things are used, either 
directly via the (:include:) markup, or indirectly via things such as
group headers/footers, pagelist templates, the <!--wiki:...--> 
directive for sidebars, and so on.

So, let's play a bit with the idea of switching (:include:)
so that links and variables refer to the included page,
and let's see what happens.  

(Of course, we would provide an option that lets existing sites 
continue with the existing behavior for include, but I'm
curious to know how much would have to be changed/fixed/updated
for an existing site to convert to a new default, if they
wanted to do that.)

1.  (:include:)

I don't know of many cases where people are relying on the
fact that links inside of an (:include:)d page are relative to
the including page.  In this case links like [[name]] would
need to be rewritten as [[{.$Group}/name]], or an option given
to include that says "relative links are based on the including page".

Usually the issue with (:include:) is the other way around; people
expect [[name]] to be relative to the included page, and when it
doesn't work they have to go in and add the group name to become
[[group/name]].  So, switching wouldn't hurt these cases.

2.  GroupHeader/GroupFooter

Group headers and footers are by definition in the same group
as the browsed page, so [[links]] aren't a problem.  However, it would
be odd if {$Name} and {$Title} referred to the GroupHeader's name
and title instead of those of the browsed page.

However, if we add a base= option to (:include:) that says things
are relative to the including page, then we can avoid the problem.
If we define $GroupHeaderFmt as

    $GroupHeaderFmt='(:include GroupHeader base={.$FullName}:)(:nl:)';

then all of the links and page variables in the GroupHeader would be
evaluated in the context of the currently browsed page, and {$Name}
and {$Title} would work as we expect.

3.  Pagelist templates

Pagelist templates that have {$Name} or {$Group} in them
(without any leading '<', '=', or '>') would have to be updated
to use {.$Name} or {.$Group} instead.

None of the core pagelist templates make any use of page variables
such as {$Name} or {$Group}, all of them strictly use things
like {<$Name} and {=$Group}.  These would continue to work as before.

Only two of the Cookbook.PagelistTemplateSamples templates make
us of an unqualified {$var}, and I think one or both of them may be
errors.  At any rate, it doesn't seem like a lot of templates would
be seriously impacted.

4.  <!--wiki:...--> directives, sidebars.

These are a lot like (:includes:), in that most authors expect
the [[links]] to be relative to the sidebar and not to the
currently browsed group.  So, this matches #1 above.  I don't know
how many sidebars are making use of things like {$Group}, {$Name},
and {$Title} -- they would have to be changed to {.$Group}, {.$Name},
and {.$Title}, or the sidebar told to use the currently browsed page
as its base.

Still, the number of sidebars is a pretty small proportion of pages,
and it's easy to find them, so perhaps this switch wouldn't be too bad.
It's the one I'm most certain would be easier for new authors to grasp,
but also the one that could cause the most problems for existing

Any comments or thoughts on this idea?  Too radical for existing
sites to swallow, or should I pursue it and see what happens?


More information about the pmwiki-users mailing list