[pmwiki-users] Custom markup - where to begin?

[Henrik Bechmann]

Just as an aside, I think the documentation could use a thorough 
overhaul, and I think the only way it's going to happen is if we do it 
collectively. Don't ask me how to get organized -- I doubt anyone has 
more time than I do. Perhaps a "PmWiki Foundation", in the classic mold 
of open source social organization?

Peter & Melodye Bowers wrote:
>> +   Where can I find the documentation for how to write one? I 
>> tried finding
>>      something but apparently didn't manage to find it.
>>     
>
> This is a question which causes difficulties because it's hard to put a
> boundary around the answer.  I'll try to be brief with the understanding
> that there are others out there with a much broader understanding of all the
> ways a "plugin" can occur in PmWiki.
>
> The most typical kind of "plugin" (I'll call it a "recipe" from here on out
> because that's how they're named in the PmWiki world) is to establish some
> kind of markup.  This means you are creating some particular "pattern" of
> text in your page which will cause some action and cause that particular
> text to be replaced with something else.
>
> You're on the correct page at PmWiki/CustomMarkup to read more about this.
> Basically creating a new markup involves first (and perhaps only?) a call to
> the PHP Markup() function (usually in your config.php, but alternately in a
> custom group or custom page PHP file -- you can read about those at
> http://www.pmwiki.org/wiki/PmWiki/LocalCustomizations).
>
> This Markup() function takes 4 arguments:
>
> 1: The arbitrary name you are going to give your new markup.  It should be
> short but descriptive.  Be careful you don't use the same name as another
> markup out there or that markup will no longer be active.  (You can see most
> markup definitions in scripts/stdmarkup.php.)  An example for you might be
> "MyPics" or "ApertureTags" or something that refers to how the pattern of
> text might look - it's arbitrary, so it's your call.
>
> 2: An indicator of WHEN you want this to occur.  PmWiki has dozens of these
> markup rules and it makes a big difference in what order they occur.  If one
> markup rules (#1) changes all occurrences of "a" into "b" and another markup
> (#2) changes all occurrences of "az" into "zz" it obviously makes a big
> difference in what order they occur.  If #1 occurs before #2 on the text
> "azazaz" then you will end up with "bzbzbz".  But if #2 occurs before #1
> then you will end up with "zzzzzz".  This argument is normally specified as
> a left-angle bracket ("before") or a right-angle bracket ("after") followed
> by the name of another rule.  In my experience the most significant rule in
> terms of ordering is "{$var}" which substitutes variables -- if you say
> "<{$var}" then your markup will be processed before variables are
> substituted whereas if you say ">{$var}" then your markup will be processed
> after variables are substituted.  But there are lots of other places in the
> whole order of rules -- someone else will have to go into more detail if you
> need it.  That CustomMarkup page gives some good pointers there.
>
> Arguments 3 and 4 are simply arguments which will be passed to preg_replace.
> You search for argument #3 and you replace it with argument #4.
>
> 3: This is a regular expression.  It can be as simple as "/a/" (match every
> occurrence of the character "a") up to very complicated and intricate
> patterns.  Every time this pattern matches in your text it will be replaced
> with argument #4.  Note that your pattern is always surrounded by forward
> slashes and there can be modifiers after the closing forward slash.  These
> modifiers are single characters which you can read more about them at
> http://www.php.net/manual/en/reference.pcre.pattern.modifiers.php.  The key
> ones are "i" (ignore case), "s" (allow dot to match newlines), "m" (allow ^
> and $ to match before/after newlines as well as begin/end of strings), and
> [perhaps most importantly in this context] "e" (evaluate the replacement
> text as a PHP expression - this allows you to call functions to do much more
> complicated things than a simple search/replace).
>
> 4: This is the replacement text.  It can be a simple string or it can
> include things like $1, $2, etc if you have parenthesized groups in argument
> #3 (you've got to be careful to put backslashes in front of the $ or else
> surround it in single-quotes, etc to delay the interpolation of those
> variables).  Or it can be a call to a PHP function if you included the /e
> modifier in argument #3.
>
> Having said all that, the single best way to learn how to write your own
> recipe or markup is to look at examples of what other people have done.
> Start with something simple and just try to figure out what it's doing.
> Then save it off (!) and change it in some way to see how it changes things.
> Then move off into your own stuff (although probably most recipe authors
> routinely start with some other similar recipe and modify it -- if for
> nothing else than to save the typing!)
>
> This may be way too basic or it may be way too theoretical, but hopefully
> it'll help get you started in the right direction.
>
> I would be happy to add this to the PmWiki/CustomMarkup page if I were
> fairly confident that someone with broader PmWiki experience would go in and
> correct my oversights and errors that I'm sure I've made here...
>
> -Peter
>
>
> _______________________________________________
> pmwiki-users mailing list
> pmwiki-users at pmichaud.com
> http://www.pmichaud.com/mailman/listinfo/pmwiki-users
>
>   

-- 

Henrik Bechmann
www.bechmann.ca
Webmaster, www.dufferinpark.ca

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.pmichaud.com/pipermail/pmwiki-users/attachments/20080426/a7e4d696/attachment.html