[pmwiki-users] Upgrade woes: PublishPDF and PmWiki 2.1beta25

[Patrick R. Michaud]

On Tue, Feb 14, 2006 at 10:04:21AM +1300, John Rankin wrote:
> 1. (:searchresults:) versus (:pagelist:)
> ...
> I have been able to work around this by changing the Markup rule 
> for this action so that (:pagelist:) markup generates 
> 
> '<:block>'.Keep(FmtPageList(...)) 
> 
> I haven't been able to work out why this is needed for pagelist 
> and not searchresults and suspect it may be a bug.

It may indeed be a bug.  I'm thinking that Keep() will become a
bit smarter and automatically recognize when it contains block
markup and use that information to prevent adding of <p>...</p>
tags around the results (this is essentially what <:block> does).

> 2. FPLByGroup function
> 
> It was a bit of a surprise to see the FPLByGroup function removed. 
> ...

Yeah, sorry about that.  Ever since it was first written (:pagelist:)
has been a bit unwieldy and I'm using 2.1 as an opportunity to refactor
a few things and clean things up.

I think it should be possible to define the publish form using
the templates... but it's not at all obvious that this is the
case at this point.  My suggestion for now is to create a 
FPLPublish() function (based on FPLByGroup) that does exactly 
what you want.  The ability to define custom FPL functions isn't
going away anytime soon.

Also, see my note at the bottom of this message regarding using
transition.php to "restore" the FPLByGroup function to the core.

> 3. Search and the current page
> 
> On Main.HomePage, when I search for 'sandbox', I get a list of 
> one page -- Main.WikiSandbox. On Main.WikiSandbox, when I search 
> for 'sandbox', I also get a list of one page -- Main.HomePage. 
> In both cases, it tells me it has searched one page. Is this a 
> bug, a feature, or a mis-configuration?

If you're using "list=normal" in a pagelist, then it's because
list=normal has recently been modified to exclude the current page
from the output listing.  Based on what you've just written, this
may be the wrong thing to do (although several have remarked that
it seemed like the right thing to do at the time).

If you're not using "list=normal", it's a bug.

> 4. $FmtV substitution
> 
> I note that by design, if the value of $FmtV['$SomeVar'] is not 
> set, FmtPageName returns '$SomeVar'. This is a real pain, as I 
> have to track down every use of $FmtV and check whether the 
> variable assigned to it is set and if not set the value to ''. 
> I'm not clear why one would want FmtPageName to return 
> '$SomeVar, except perhaps for testing, so wonder if perhaps 
> there might be an option one could set to tell FmtPageName 
> what to do if the value of $FmtV['$SomeVar'] is not set. 
> Then I could tell it "always return ''".

This particular design has been in place for a long time.
The reasoning is that sometimes strings get passed to FmtPageName
that indirectly contain dollar signs (e.g. from other variable
substitutions, perhaps from author markup) that aren't supposed 
to be treated as global markup.  So, FmtPageName has always
performed substitutions only for variables that actually exist.

I think the larger question here is... why are there dollar-signs
in the format strings being passed to FmtPageName that don't
correspond to substitution variables?

> 5. $FmtP versus $FmtPV
> 
> I note that variables once set in $FmtP are now set in $FmtPV. 
> It appears that if the same substitution variable is set in 
> both places, $FmtP takes precedence. 

2.1 now makes a distinction between "page variables" and
"global variables".  A page variable with curlies like "{$Var}"
always uses $FmtPV (and substitutes a null string if the
page variable isn't defined).

$FmtP really exists primarily to preserve backwards compatibility.
For this reason, a substitution variable without curlies first
looks in $FmtP (which is where historical recipes would've
placed the definition) before looking in $FmtPV.  So, for example,
a recipe that defined a custom "$Title" substitution (in $FmtP) 
should expect to retain its superiority even though PmWiki now 
defines $Title using $FmtPV.

> Will this continue to be 
> the case or should I track down all occurrences of $FmtP and 
> change them to $FmtPV? 

Ideally, recipes will start to use $FmtPV and "{$PageVar}" in 
preference to $FmtP -- it's both faster and a bit more flexible 
in terms of what can be substituted.   However, I don't expect
to be eliminating or changing the priority of $FmtP anytime soon,
so it should be safe to continue using it.

----

On another note, starting with recent 2.1.beta releases the PmWiki
"backwards compatibility layer" (in scripts/transition.php) is
a lot more flexible and fine-grained than before.  Previously,
admins and recipes were pretty well constrained to requesting
all-or-none of the compatibility adjustments defined there.

Starting with 2.1.beta24, admins (and recipes) can request specific
compatibility features to be loaded by setting flags in the $Transition
array.  For example, 2.0.beta44 moved the AllRecentChanges page
from Main to $SiteGroup.  If a site or recipe wants to preserve the
previous Main.AllRecentChanges behavior, one can set

    $Transition['mainrc'] = 1;

Each transition has its own identifier (which at the moment can
only be found by looking at the transitions.php file).

All of the transitions since a specific version of PmWiki can be
loaded by setting $Transition['version'], thus

    $Transition['version'] = 2000013

would say to load all transitions that have been defined to
preserve 2.0.13 compatibility in later versions of PmWiki.  (None
have been defined yet for 2.0.13, but if/when any are, this
setting will cause them to be loaded.)

So, if there's a specific "core setting" that has been changed
or removed from the default configuration and that recipes or sites
would like to see preserved, just let me know and I'll add it into
transition.php .

As a prime example of this, I don't have any issue with adding
FPLByGroup() (and the other now-missing FPL functions) into
transition.php.  Then a recipe that expects FPLByGroup to be
available could do:

    $Transition['fplbygroup'] = 1;

and the FPLByGroup function would be automatically loaded from
transition.php even though it's no longer used by the core.

Hope this helps,

Pm