version=pmwiki-2.0.beta23
newline=²
text=PmWiki's markup translation engine is handled by a set of rules; each rule searches for a specific pattern in the markup text and replaces it with some replacement text.  Internally, this is accomplished by using PHP's "[[(http://www.php.net/)preg_replace]]" function.²²Rules are added to the translation engine via PmWiki's Markup() function, which looks like²²   Markup($name,$when,$pattern,$replace)²²where [@$name@] is a unique name (a string) given to the rule, [@$when@] says when the rule should be applied relative to other rules, [@$pattern@] is the pattern to be searched for in the markup text, and [@$replace@] is what the pattern should be replaced with.²²For example, here's the code that creates the rule for [@''emphasized text''@] (in ''scripts/stdmarkup.php''):²²   [=Markup("em","inline","/''(.*?)''/","<em>$1</em>");=]²²Basically this statement says to create a rule called "em" to be performed with the other "inline" markups, and the rule replaces any text inside two pairs of single quotes with the same text ($1) surrounded by [@<em>@] and [@</em>@].²²The first two parameters to Markup() are used to specify the sequence in which rules should be applied.  The first parameter provides a name for a rule -- "[@em@]" in the example above.  We could've chosen other names such as "[@''@]", or even "[@twosinglequotes@]".  In general PmWiki uses the markup itself to name the rule (i.e., PmWiki uses "[@''@]" instead of "[@em@]"), but to keep this example easier to read later on we'll use a mnemonic name for now.²²The second parameter says that this rule is to be done along with the other "inline" markups.  PmWiki divides the translation process into a number of phases:²²   _begin          start of translation²   fulltext        translations to be performed on the full text            ²   split           conversion of the full markup text into lines to be processed²   directives      directive processing²   inline          inline markups²   links           conversion of [[links]], url-links, and WikiWords     ²   block           block markups²   style           style handling       ²   _end            end of translation²²Thus, specifying "inline" for the second parameter says that this rule should be applied when the other "inline" rules are being performed.  If we want a rule to be performed with the directives -- i.e., before inline rules are processed, we would specify "directives" for the second parameter.²²Here's a rule for [@@@monospaced@@@] text²²   [=Markup("@@","inline","/@@(.*?)@@/","<code>$1</code>");=]²²and for a [@[:comment ...:]@] directive that is simply removed from the output:²²   [=Markup("comment","directives","/\\(:comment .*?:\\)/",'');=]²²Okay, now how about the rule for [@'''strong emphasis'''@]?  We have to be a bit careful here, because although this translation should be performed along with other inline markup, we also have to make sure that the rule for [@'''@] is handled ''before'' the rule for [@''@], because [@'''@] also contains [@''@]. The second parameter to Markup() can be used to specify the new rule's relationship to any other rule:²²   [=Markup("strong","<em","/'''(.*?)'''/","<strong>$1</strong>");          =] ²²This creates a rule called "strong", and the second parameter "<em" says to be sure that this rule is processed before the "em" rule we defined above.  If we wanted to do something after the "em" rule, we would use ">em" instead.  Thus, it's possible to add rules at any point in PmWiki's markup translation process in an extensible manner.  (In fact, the "inline", "block", "directives", etc., phases above are just placeholder rules used to provide an overall sequence for other rules.  Thus one can use "<inline" to specify rules that should be handled before any²other inline rules.)             ²²If you want to disable available markup just call e.g.:²²   [=Markup("strong","<em");          =] ²²The lack of a pattern & replacement parameters indicates that you simply wish to disable the markup.²²PmWiki's default markup rules are defined in the ''scripts/stdmarkup.php'' file.  To see the entire translation table as the program is running, the scripts/diag.php module adds "[@?action=ruleset@]", which displays the set of defined markup rules in the sequence in which they will be processed.  You can see it at CustomMarkup?action=ruleset.²²more examples: \\²'''Call a user function which returns some content:''' \\²The markup [=(:meeting:)=] calls the global function meeting() - which may be located in config.php - and returns the date of the next BLUG-Meeting as a string. ²²   [=Markup('meeting', 'directives', '/\\(:meeting:\\)/e',"meeting()");=]  ²²%blue%It took me a while to understand this. Is it the 'e' behind the regexp, that causes PmWiki to evaluate the function rather than replaceing [=(:meeting:)=] by [=meeting()=] ?? -- Nils ²²%Pm% Yes.  --[[~Pm]]²²²%trail%<<|PmWiki.DocumentationIndex|>>
time=1109710581
name=PmWiki.CustomMarkup
host=24.1.28.47
agent=Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.7.5) Gecko/20041107 Firefox/1.0
rev=17
author=Pm
targets=PmWiki.PmWiki,PmWiki.Links,PmWiki.WikiWords,PmWiki.CustomMarkup,Profiles.Pm,PmWiki.CustomInterMap,PmWiki.CustomWikiStyles,PmWiki.DocumentationIndex