Summary: Document a "recommended" way to use core functions from config files
Created: 2010-07-28 04:01
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.