[pmwiki-users] question regarding PMWiki's function markup

[Patrick R. Michaud]

On Sat, Mar 04, 2006 at 10:32:00PM +0000, Jae Lee wrote:
> Hi there,
> 
> i've been trying to understand pmwiki.php recently... and Markup is
> one of the functions that I got stuck...
> 
> Can you briefly explain the semantic meaning of $MarkupTable
> structure? especially,
> 
> 1. $MarkupTable[$id]['dep']
> 2. $MarkupTable[$id]['seq']
> 
> with respect to Markup("loginform", "_end", "/\\(:loginform:\\)/",
> GetUserLoginForm(true)) ?

I'm a little curious as to the reason for the question, because
in order to use the Markup() function one really shouldn't have
to know anything about the $MarkupTable.

But, in order to answer your question, the above Markup() call
says that a markup called "loginform" should occur within the
"_end" section, using the pattern and replacement given.

The key to getting markups to work is making sure they are performed
in the correct sequence -- for example, it's important that
the ''' markups get processed before the '' markups, that
url links are processed before wikiword links, etc.  So, PmWiki
gives every markup rule a unique name, and every rule can
specify when it should be executed relative to some other rule:

    "<xyz"   Perform this markup rule before the "xyz" rule.
    ">xyz"   Perform this markup rule after the "xyz" rule.
    "xyz"    Perform this markup rule "within" the "xyz" rule 
             (this means after the xyz rule itself, but before
             any rules that are marked as being after the xyz rule).

The rest of the message gets into the Deep Magic that goes on
in markup sequencing, and it's perfectly okay for readers to tune
out at this point.  :-) :-)

The 'seq' elements in $MarkupTable simply provide a key string that 
PmWiki can use to sort the markups into their proper sequence
prior to processing.  The idea is that we can easily determine the
sequence key of a new rule based on its relationship to another rule
and the sequence key for that other rule.  Let me know if you
*really* want more details about how this works, but you can
see the sequence keys being used on pmwiki.org by looking at
the third column of http://www.pmwiki.org/wiki?action=ruleset .
Notice that the sequence keys are in sorted order, and that 
every markup rule has the correct relationship to the one it
depends on (as given by the second column).

The 'dep' elements keep track of the dependencies between markups.
Consider the following pair of Markup() calls:

    Markup("''", "inline", "/''(.*?)''/", "<em>$1</em>"); 
    Markup("'''", "<''", "/'''(.*?)'''/", "<strong>$1</strong>");

(Apologies in advance for all of the quote marks that are in the
description that follows, it just turns out that this is the easiest
pair of rules to demonstrate the principle with.)

Here, we say that the '' markup is part of the "inline" section.
Since the "inline" rule is already defined by pmwiki.php, we can
immediately determine the 'seq' key for the '' markup based on
the 'seq' key of the "inline" markup.  Similarly, when processing
the ''' markup, we can determine its 'seq' key from the 'seq' key of
the '' markup.

But look what has to happen if we reverse the order of these
two statements:

    Markup("'''", "<''", "/'''(.*?)'''/", "<strong>$1</strong>");
    Markup("''", "inline", "/''(.*?)''/", "<em>$1</em>"); 

We still want the ''' markup to depend on the '' rule, but
we can't determine its sequence key yet because the '' rule hasn't
been defined yet.   Some people would say "Well, just make sure to
always define the ''' rule after the '' rule", but that's not really
practical in PmWiki, where a cookbook recipe may need to define
a markup relative to some other markup rule that is to be defined
later in processing.

So, what PmWiki does in this situation is to put an entry in the 
'dep' slot for the '' rule that essentially says "When the sequence
key of the '' rule becomes known, go compute the sequence key of
the ''' rule as well."  

In other words, the 'dep' entries allow us to make calls to
Markup() in any sequence that we want and still have the markup
rules get the appropriate sequence keys.

If you're curious about the sequence keys, you can see the sequence
keys being used in pmwiki.org's markup rule table by looking at
the third column of http://www.pmwiki.org/wiki?action=ruleset .
Note that they're in sorted order, and that every rule has the
correct relationship to the one it depends on (as given by
the values in the second column).

Hope this helps; if there are further questions feel free to ask.  :-)

Pm