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

Patrick R. Michaud pmichaud
Mon Sep 6 09:29:58 CDT 2004


On Mon, Sep 06, 2004 at 01:02:32PM +1200, John Rankin wrote:
> [The Markup function] looks superb!
> 
> Let me test a scenario, which appears not easy in 1 (?) but entirely
> possible in 2.
> An author wants to insert a
>     [:newpage:]
> directive to break up a long page into readable chunks.
> In browse view, pmwiki initially displays the text up to the first
> [:newpage:] directive, plus a 
>     Page 1 2 3 ...
> line. [...]
> 
> So with PmWiki 2, it's something like:
>     Markup("newpage",">include","/\\[:newpage:\\]/e", then I get lost...
> So how do I invoke this?

Discussion below, but for demonstration purposes I've implemented this 
feature at http://www.pmwiki.org/pmwiki2/pmwiki.php/Cookbook/BreakPage .  
The code is at http://www.pmwiki.org/pmwiki2/uploads/Cookbook/breakpage.php .

I decided to name the directive [:breakpage:] instead of [:newpage:] 
because "new page" means something else to me (i.e., create a "new 
wiki page").  Of course we can change this to something else.

The call to insert the markup is basically:

  Markup('breakpage','>include','/^.*\\[:breakpage:\\].*$/se',
    "PageBreak(\$pagename,PSS('$0'))");

which says the new markup is called "breakpage", it's to be performed
after the "include" markup, and the pattern to be matched is any text
that has [:breakpage:] in it.  If that pattern is matched, then call
PageBreak(), passing the name of the page being processed and the
entire text matched ('$0' has the entire text because of the ^.* and
.*$ anchors in the pattern).

The PSS(...) function around '$0' is provided by PmWiki to get rid of 
the backslashes that the /e option likes to put in front of double 
quotes in the matched string.

The PageBreak() function then simply splits the text by [:breakpage:],
extracts the relevant portion, adds the "Page 1 2 3 ..." links to the
end, and returns that text to be processed.

------

If the above makes any sense, then it might be worthwhile to stop 
reading here.  :-)  However, there's another option to Markup() that 
I haven't documented yet (just haven't figured out how to describe
it cleanly)...

Using a pattern match to process the entire text may not be the
most efficient mechanism in the world, so PmWiki 2 offers an
alternative to using preg_replace for markup translations.  If the 
third argument call to Markup() doesn't begin with a slash, then 
it's a substring to be searched for in the text, and the replacement is 
PHP code to be processed with eval().  

  Markup('breakpage','>include','[:breakpage:]',
    'return PageBreak($pagename,$x);');

says that if the text being processed contains the string '[:breakpage:]',
then replace it with the value returned by a call to PageBreak().
$x is the entire text being processed (analogous to $Text in PmWiki 1).
For some operations this may be more efficient, but it always
replaces the entire string with the value returned from the code,
and you don't have the text matching/extraction possibilities that
preg_replace provides.

Pm



More information about the pmwiki-users mailing list