[pmwiki-users] variables for customization

[Patrick R. Michaud]

On Thu, Jul 07, 2005 at 05:16:50AM +0200, Joachim Durchholz wrote:
> It's been frustrating and enraging to me trying to clear up what Pm and 
> me are actually talking about, which of these various namespaces follow 
> what rules. Seems like we were talking at cross-purpose, and that there 
> are not just two but (at least!) three namespaces involved: PHP 
> variables, wikipage markup variables, and those strange *Fmt variables 
> which seem to be a recurring pattern that I haven't been able to really 
> understand yet.

With apologies for the frustration many are feeling, let me at least try 
to clear up this last point about the *Fmt variables.

In order to produce its output, PmWiki has to do a variety of
string substitutions:
  1. Generating the full name, group, title, or url of a page
     (other than the currently displayed page)
  2. Substituting the values of global variables
  3. Performing internationalization substitutions
  4. Converting $ScriptUrl/$Group/$Name to $ScriptUrl?n=$Group.$Name
     for sites that cannot handle PATH_INFO urls
  5. Other substitutions needed by specific functions

PmWiki centralizes all of that substitute-a-dynamic-value-in-a-string 
into the FmtPageName() subroutine.  Because some things are extremely
dynamic, such as the url or group for an arbitrary page that
is not the current one, those things cannot be simple global PHP 
variables.  Or, if they do become global variables, they're 
variables that cannot be trusted to hold a value for very long 
because some other routine (that may happen to be formatting a
string for a different page) will come along and change that
global variable for whatever it happens to be doing.

In chosing the syntax for FmtPageName(), it seemed pretty obvious 
that to substitute the values of global variables we should use 
something like $VarName.  It also made good sense to use $[phrase] 
to indicate an internationalization substitution.  For the other 
substitutions, rather than come up with a special character for
them, and make skin authors and recipe writers have to remember
when they should use '$' versus some other special character
sequence, I just decided that '$' would be used to indicate *all*
string substitutions regardless of source.  There's ample precedence 
for this in many languages including PHP, shell scripts, awk, etc.  
Languages that have attempted to use different "sigils" for 
different types of substitution have often just changed one source 
of confusion for another.  And this is the correct choice for
the vast majority of admins who are just trying to design a skin 
or make a simple configuration change, who don't need to be 
bothered with details about whether something is internally a 
global variable or something more dynamic.  I didn't want to
have to explain to a skin writer, who knows nothing about PHP
internals, why they sometimes have to write (say) "?Group", "?Title",
and "?PageUrl" but other times write "$WikiTitle", "$PageLogoUrl",
"$SkinDirUrl".  

For the vast majority of site admins, the use of $VarName 
for both global and dynamic values "just works", and has done
so nicely for over three years.

As far as keeping thing straight for those who need to understand
the differences, there are really only three things to know.  

1.  Things like "{$Group}" and "{$LastModified}" are *markup*.  
    You can call them "variables" or "markup variables" if it pleases 
    you, but they don't really exist as variables anywhere in the 
    PmWiki code, nor is there an enforced correspondence between them
    and any PHP variable.  They're just substitutions in the Markup() 
    sequence, the same as [=...=] or (:include:) or (:table:) or 
    any other markup.

2.  A limited set of $-substitutions -- basically anything that 
    corresponds to a page attribute -- are not PHP variables and 
    are only available through the FmtPageName() subroutine.  
    The complete set of these special substitutions is $Group, 
    $Name, $FullName, $PageUrl, $Title, $Titlespaced, $Namespaced, 
    $Groupspaced, $LastModifiedBy, $LastModifiedHost, and $LastModified.  
    These items cannot just be standard PHP variables because often
    PmWiki needs to obtain the url, name, group, title, etc. of a page 
    other than the one currently being viewed by a browser.

3.  With minor exceptions, basically everything else you see that
    looks like $VarName is a PHP variable.

Pm