[Pmwiki-users] DoubleBrackets, LinkPatterns, and InlineReplacements

[pmichaud at pobox.com]

Since a few people have asked, here's a brief summary of the
$DoubleBrackets, $LinkPatterns, and $InlineReplacements arrays and how
they work/interact.  These arrays were designed to allow wiki administrators
to create custom markups without having to modify pmwiki.php to achieve
them.  Here's a brief description of the variables:

$DoubleBrackets contains the substitutions to make before making WikiWord,
URL, and other "link" substitutions.  It generally handles the conversions
of things like "[[$Group]]", "[[$Title]]", "[[spacewikiwords]]", 
"[[$LastModified]]", etc., which is how it got its name.

$LinkPatterns specifies the rules for converting WikiWords, freelinks,
URLs, InterMap links, etc. into HTML.  

$InlineReplacements specifies the substitutions to make after most of
the other structural markup has been handled.  These include things
such as bold/italic text, character entitites, larger/smaller text,
and horizontal rules.

The sequence PmWiki uses to convert wiki markup to HTMl approximates
something like the following:
 1. replace HTML special characters (&, <, >) with entities (&amp; &lt; &gt;)
 3. save all text inside of [=...=] so it doesn't get processed
 4. process replacements listed in $DoubleBrackets
 5. convert sequences matching $LinkPatterns to HTML and save for step 8
 6. output "structural" HTML for paragraphs, tables, preformatted text, 
    lists, headers, etc.
 7. convert replacements given in $InlineReplacements
 8. restore the HTML links produced from step 5
 9. process and apply WikiStyles
 10. restore the things in [=...=] from step 2

Thus, $DoubleReplacements specifies translations to be performed before
doing any processing of things held in the $LinkPatterns array, and
$InlineReplacements specifies the conversions to be made to handle
"inline" sorts of markup after $LinkPatterns and structural markup are done.

The entries in $DoubleBrackets are associative arrays; the keys (indexes)
are replaced by their corresponding values.  Thus

   $DoubleBrackets["[[Pm]]"] = "[[PatrickMichaud Pm]]";

will replace all occurrences of "[[Pm]]" in the markup with 
"[[PatrickMichaud Pm]]".  This takes place before LinkPatterns are processed,
so the text after substitution will be treated as if the user had entered
it directly.  Also, the values from $DoubleBrackets are processed using
FmtPageName, so things like '$Group', '$Titlespaced', '$PageUrl', etc. 
are replaced with their appropriate values for the page being processed.

The entries in $InlineReplacements are associative arrays; the keys are
regular expressions to be matched, and the values are the replacement
strings (via PHP's preg_replace function).  

   #### superscripts via ^^text^^, subscripts via __text__
   $InlineReplacements['/\\^\\^(.*?)\\^\\^/'] = "<sup>\$1</sup>";
   $InlineReplacements['/__(.*?)__/'] = "<sub>\$1</sub>";

   #### a simple smiley to gif conversion
   $InlineReplacements['/:-)/'] = 
     '<img src="http://www.example.com/smileys/happy.gif" alt=":-)">';

Note that the $InlineReplacement keys must include regular expression
delimiters (normally slashes).  Also note that the smiley example could
not have been done using $DoubleBrackets because the src="http://..."
would've been picked up and modified by the $LinkPatterns.

The $DoubleBrackets array will also a regular expression search/replace
(via preg_replace) for any keys that begin with a slash.

Finally, $LinkPatterns works a bit like $DoubleBrackets and 
$InlineReplacements, but is more complex because of the variety of
replacements to be performed and the fact that order is very significant.
The first index of $LinkPatterns entries specifies the sequence in
which to process the patterns, the second index specifies the regular
expression pattern to match, and the value of the entry specifies either
the replacement string or the name of a function to be called to provide
the replacement string.  Thus:

   $LinkPatterns[200]["\\bmailto:($UrlPathPattern)"] = "<a href='$0'>$1</a>";

says to replace the markup text like "mailto:someone at example.com" 
with "<a href='mailto:someone at example.com'>someone at example.com</a>",
and to do this after $LinkPatterns numbered less than 200 but before
$LinkPatterns numbered higher than 200.  The statement

   $LinkPatterns[120]["\\bAttach:($UploadNamePattern)"] = 'FmtAttachLink';

says to replace Attach: markup by calling the FmtAttachLink function.

The standard sequence of replacements in a PmWiki distribution are
currently:

   100   ThisWiki:, ThisGroup:, ThisPage: links (from thiswiki.php)
   120   Attach: links (from upload.php)
   200   mailto: links
   300   http:, ftp:, gopher:, etc. links
   400   InterMap links
   500   Group/{{free links}}  and Group.{{free links}}
   600   {{free links}}
   700   Group/WikiWords  and Group.WikiWords
   800   WikiWords

Note that unlike $InlineReplacements, the regexps in $LinkPatterns 
cannot include the regular expression delimiters.  

Anyway, hopefully this sheds a little light the role that these
arrays play in PmWiki's markup to HTML conversion for those who
are wanting to add their own customized markups.  Of course, if
anyone has any questions, feel free to write me or the listserv.

Pm