[Pmwiki-users] PmWiki 2 custom markup, draft 1

[Patrick R. Michaud]

This message briefly describes how one goes about adding custom markup
in PmWiki 2.0.  I'm also adding this as the PmWiki.CustomMarkup page
on pmwiki.org, so changes can go there.

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
"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
   links           conversion of [[links]], url-links, and WikiWords
   block           block markups
   inline          inline 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
links 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.)

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 display the 
set of defined markup rules in the sequence in which they will be processed.  
You can see it at http://www.pmwiki.org/pmwiki2/pmwiki.php?action=ruleset .

Questions and updates to this information are greatly appreciated, you
can send them to me, pmwiki-users, or post them on the PmWiki.CustomMarkup
page.

Pm