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

[Peter & Melodye Bowers]

> +   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