01145: sample-config.php: confusing descriptions for EnableRelativePageVars, EnableWSPre

Summary: sample-config.php: confusing descriptions for EnableRelativePageVars, EnableWSPre
Created: 2009-10-03 05:41
Status: Closed - fixed for 2.2.9
Category: Documentation
From: Rogutės?
Priority: 2
Version: 2.2.5
OS: -

Description: sample-config.php contains misleading information, namely:

Though looking at scripts/stdmarkup.php, there is this line: SDV($EnableWSPre, 1);. Probably the code and not the documentation is incorrect in this case.
  • In the 2.2.0-beta series, {$var} page variables are absolute by default, but a future version will make them relative. <...>
    $EnableRelativePageVars = 1; 
This seems to indicate that it is already the default, since we are out of beta for some time now.

Yes, the plan was to have them both changed, $EnableWSPre to 0 and $EnableRelativePageVars to 1, but we didn't in the change to 2.2.0 stable. I'll think about documenting it well, and we'll probably change it in a while. For the moment, I fixed sample-config.php to show the current status. --Petko December 11, 2009, at 04:04 AM

Version 2.2.9 will change $EnableRelativePageVars to 1, but will not change $EnableWSPre. Everything is now correctly documented. --Petko January 16, 2010, at 10:17 PM

In pmwiki-2.2.122 the description for $EnableRelativePageVars is still confusing, I think.
It does not say if this option has any effect, by default.
And if this option is active, which is the default value?
Although we can assume that the default value is "1", by the given example.
But is it active?
Maybe a better description and a link to page PmWiki.BasicVariables#EnableRelativePageVars would help.
nikos? December 05, 2019, at 03:06 AM

Here is the current description:

This setting controls how Page variables in included pages are understood by PmWiki.
$EnableRelativePageVars = 1; # PmWiki current default
In this case {$Name} displays the name of the physical page where it written. If {$Name} is in an included page, it will display the name of the included page. (This is currently PmWiki's default.)
$EnableRelativePageVars = 0; # revert to previous default
In this case {$Name} displays the name of the currently browsed page. Even if {$Name} is in an included page, it will display the name of the browsed page. This was PmWiki's default in versions 2.2.8 and earlier, and changed in 2.2.9, but you can revert it back with this line in config.php.
{*$Name} with an asterisk always displays the name of the currently browsed page, regardless of $EnableRelativePageVars.

The texts I've emphasized here in orange say (twice) that this is the default value. Like with all other variables, you don't need to set this if you are happy with the default value, and setting it to 1 will indeed have no effect - it is already set to 1. Only setting it to 0 will have effect. I've checked that this has been included in the documentation that ships with PmWiki since February 2010 -- almost 10 years ago. How do you suggest this can be improved? --Petko December 05, 2019, at 08:18 AM

- - -

I think I was not very clear. I am talking specifically about the description on sample-config.php (as the title of the issue says...). Which currently reads as follows...

   In the 2.2.0-beta series,  page variables were absolute, but now
   relative page variables provide greater flexibility and are recommended.
   (If you're starting a new site, it's best to leave this setting alone.)
   $EnableRelativePageVars = 1; # 1=relative; 0=absolute

One way of reading the above is...

They were "absolute" (which means... maybe some php term?...), but now they are recommended, but although they are recommended, you should not touch this setting, because... ? ? ? (is it already enabled? is it too "advanced" ? is this option really not needed?)

And, I was trying to make a new pmwiki testing installation, but transfer the old data (/uploads, /wiki.d, /cookbook, etc) from the old installation. Which adds to the confusion.
nikos? December 19, 2019, at 01:51 PM

I agree with you -- it is indeed confusing and should be removed from sample-config.php -- all the documentation, templates and included sections use the new default now. I also really dislike the terms "relative" and "absolute" that were chosen at the time -- we can change those if we find better ones. --Petko December 19, 2019, at 05:14 PM