• View
• Edit
• History
• Attach
• Print

01214

Description: From a discussion with DaveG :

>> Something else that is particularly inconsistent is documentation around
>> the use of functions like ResolvePagename, PageTextVars, etc, for config
>> processing.
>>
>> For instance, *in general* documentation suggests the use of PageVar to
>> determine group/page for specific config settings ie,
>> PmWiki/GroupCustomizations). Which contradicts the generally suggested
>> flow to use these types of functions only at the end of config
>> processing. Combine this with documentation around config/farm/group
>> config processing, and it's pretty inconsistent, and very spread out
>> across many pages.
>
> I agree that there is a problem, only it is not about how to document it, the
> problem is *using* these functions too early. I don't think these functions
> were designed to be used from config files, and they shouldn't be used.
We're deviating a little away from the documentation topic we started 
with, but if the functions were not designed to be used in the manner 
they are now being used, then we should document that. In addition 
though, we should be providing a way to get the information these 
functions provide from within config -- and then documenting it.

> (eg. PageVar should be used from inside functions, called by Markup() rules.)
This is a good example. There are many use cases where it would be 
useful to have page attribute values from config. I understand PageVar 
shouldn't be used for that, but perhaps we need to come up with a way to 
either enable PageVar to be used in these situations, or provide an 
alternate mechanism. That mechanism may be a new function(s), or might 
simply be helping developers utilize existing functions more 
appropriately. The key here, it to provide support at a level it can be 
understood -- not everyone is at the same level of coding sophistication 
-- and document it in a consistent way.


> If you want to enable or disable something for a single group or page, you are
> supposed to use the Group.php, Group.Page.php or default.php scripts. A recipe
> that wants to be run after group/page customizations should include
> pgcust.php, that should be the standard recommendation for such situations.
Again, we're away from documentation, but briefly, Group configs may 
not be a reasonable solution in all cases, so perhaps some alternatives 
need to be considered. For instance, some config needs to occurr in all 
Groups, except one. Can't do that from Group config. The documentation 
that would help here, is a single consistent way to determine the Group 
from config.php -- we use that recommendation moving forward, and strike 
the ways from the wiki.


> The next version 2.2.17 will allow you to include scripts or to call functions
> even after stdconfig.php.
I noticed that activity on the wiki, but the discussion went over my head.


> The advice about calling these functions at the end of config.php was mostly
> added by me. At the time I thought that using them this way would create less
> problems, but unfortunately that was not the bestest thing to do. If we notice
> a side-effect instead of a designed feature, we probably shouldn't rush to
> document it -- people could start building on it. :-)
Very true. But in these cases, lets come up with the 'recommended' way, 
and document it. Overrride the older advice. I'd be happy to document 
these things (as would others I'm sure), but I'm rarely sure of the 
recommended way.