Convert wiki creole 1.0 markup to xhtml
Version 0.07
Text::WikiCreole implements the Wiki Creole markup language, version 1.0, as described at http://www.wikicreole.org. It reads Creole 1.0 markup and returns \s-1XHTML\s0.
use Text::WikiCreole; creole_plugin \&myplugin; # register custom plugin parser my $html = creole_parse($creole_text); ...
Self-explanatory. Takes a Creole markup string argument and returns HTML.
Creole 1.0 supports two plugin syntaxes: << plugin content >> and <<< plugin content >>>
Write a function that receives the text between the <<>> delimiters as $_[0] (and not including the delimiters) and returns the text to be displayed. For example, here is a simple plugin that converts plugin text to uppercase:
sub uppercase_plugin { $_[0] =~ s/([a-z])/\u$1/gs; return $_[0]; } creole_plugin \&uppercase_plugin;
If you do not register a plugin function, plugin markup will be left as is, including the surrounding << >>.
You may wish to customize [[ links ]], such as to prefix a hostname, port, etc.
Write a function, similar to the plugin function, which receives the URL part of the link (with leading and trailing whitespace stripped) as $_[0] and returns the customized link. For example, to prepend "http://my.domain/" to pagename:
sub mylink { return "http://my.domain/$_[0]"; } creole_link \&mylink;
If you want complete control over links, rather than just modifying the URL, register your link markup function with creole_link() as above and then call creole_customlinks(). Now your function will receive the entire link markup chunk, such as [[ some_wiki_page | page description ]] and must return HTML.
This has no effect on "bare" link markup, such as http://cpan.org.
Same purpose as creole_link, but for "bare" link markup.
sub mybarelink { return "$_[0].html"; } creole_barelink \&mybarelink;
Same purpose as creole_customlinks, but for "bare" link markup.
Same purpose as creole_link, but for image URLs.
sub myimg { return "http://my.comain/$_[0]"; } creole_img \&myimg;
Similar to creole_customlinks, but for images.
You may wish to customize the opening and/or closing tags for the various bits of Creole markup. For example, to assign a CSS class to list items:
creole_tag("li", "open", "<li class=myclass>");
Or to see all current tags:
print creole_tag();
The tags that may be of interest are:
br dd dl dt em h1 h2 h3 h4 h5 h6 hr ilink img inowiki ip li link mono nowiki ol p strong sub sup table td th tr u ul
Those should be self-explanatory, except for inowiki (inline nowiki), ilink (bare links, e.g. http://www.cpan.org), and ip (indented paragraph).
Here is a summary of the official Creole 1.0 markup elements. See http://www.wikicreole.org for the full details.
Headings: = heading 1 -> <h1>heading 1</h1> == heading 2 -> <h2>heading 2</h2> ... ====== heading 6 -> <h6>heading 6</h6>
Various inline markup: ** bold ** -> <strong> bold </strong> // italics // -> <em> italics </em> **// both //** -> <strong><em> both </em></strong> [[ link ]] -> <a href="link">link</a> [[ link | text ]] -> <a href="link">text</a> http://cpan.org -> <a href="http://cpan.org">http://cpan.org</a> line \\ break -> line <br /> break {{img.jpg|alt}} -> <img src="img.jpg" alt="alt">
Lists: * unordered list <ul><li>unordered list</li> * second item <li>second item</li> ## nested ordered -> <ol><li>nested ordered</li> *** uber-nested <ul><li>uber-nested</li></ul> * back to level 1 </ol><li>back to level 1</li></ul>
Tables: |= h1 |= h2 -> <table><tr><th>h1</th><th>h2</th></tr> | c1 | c2 <tr><td>c1</td><td>c2</td></tr></table>
Nowiki (Preformatted): {{{ <pre> ** not bold ** ** not bold ** escaped HTML: -> escaped HTML: <i> test </i> <i> test </i> }}} <pre>
{{{ inline\\also }}} -> <tt>inline\\also</tt>
Escape Character: ~** not bold ** -> ** not bold ** tilde: ~~ -> tilde: ~
Paragraphs are separated by other blocks and blank lines. Inline markup can usually be combined, overlapped, etc. List items and plugin text can span lines.
In addition to OFFICIAL MARKUP, Text::WikiCreole also supports the following markup:
Plugins: << plugin >> -> whatever you want (see creole_plugin above) <<< plugin >>> -> whatever you want (see creole_plugin above) Triple-bracket syntax has priority, in order to allow you to embed double-brackets in plugins, such as to embed Perl code.
Inline: ## monospace ## -> <tt> monospace </tt> ^^ superscript ^^ -> <sup> superscript </sup> ,, subscript ,, -> <sub> subscript </sub> _\|_ underline _\|_ -> <u> underline </u> (TM) -> ™ (R) -> ® (C) -> © ... -> … -- -> –
Indented Paragraphs: :this -> <div style="margin-left:2em"><p>this is indented is indented</p> :: more indented <div style="margin-left:2em"><p> more indented</div></div>
Definition Lists: ; Title -> <dl><dt>Title</dt> : item 1 : item 2 <dd>item 1</dd><dd>item 2</dd> ; Title 2 : item2a <dt>Title 2</dt><dd>item 2a</dd></dl>
Jason Burnett, \*(C`<jason at jnj.org>\*(C'
Please report any bugs or feature requests to \*(C`bug-text-wikicreole at rt.cpan.org\*(C', or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Text-WikiCreole>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
You can find documentation for this module with the perldoc command.
perldoc Text::WikiCreole
You can also look for information at:
AnnoCPAN: Annotated \s-1CPAN\s0 documentation <http://annocpan.org/dist/Text-WikiCreole>
\s-1CPAN\s0 Ratings <http://cpanratings.perl.org/d/Text-WikiCreole>
\s-1RT:\s0 \s-1CPAN\s0's request tracker <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Text-WikiCreole>
Search \s-1CPAN\s0 <http://search.cpan.org/dist/Text-WikiCreole>
The parsing algorithm is basically the same as (and inspired by) the one in Document::Parser. Document::Parser is \s-1OO\s0 and is, as such, incompatible with my brain.
Copyright 2007 Jason Burnett, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.