Jason Burnett > Text-WikiCreole-0.07 > Text::WikiCreole

Download:
Text-WikiCreole-0.07.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  3
Open  5
View/Report Bugs
Module Version: 0.07   Source  

NAME ^

Text::WikiCreole - Convert Wiki Creole 1.0 markup to XHTML

VERSION ^

Version 0.07

DESCRIPTION ^

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 XHTML.

SYNOPSIS ^

 use Text::WikiCreole;
 creole_plugin \&myplugin; # register custom plugin parser

 my $html = creole_parse($creole_text);
 ...

FUNCTIONS ^

creole_parse

    Self-explanatory.  Takes a Creole markup string argument and 
    returns HTML. 

creole_plugin

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

creole_link

    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;

creole_customlinks

    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.

creole_barelink

    Same purpose as creole_link, but for "bare" link markup.

    sub mybarelink {
      return "$_[0].html";
    }
    creole_barelink \&mybarelink;

creole_custombarelinks

    Same purpose as creole_customlinks, but for "bare" link markup.

creole_img

    Same purpose as creole_link, but for image URLs.

    sub myimg {
      return "http://my.comain/$_[0]";
    }
    creole_img \&myimg;

creole_customimgs

    Similar to creole_customlinks, but for images.

creole_tag

    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).

OFFICIAL MARKUP ^

    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>           &lt;i&gt; test &lt;/i&gt;
    }}}                     <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.

EXTENDED MARKUP ^

    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)                ->    &trade;
    (R)                 ->    &reg;
    (C)                 ->    &copy;
    ...                 ->    &hellip;
    --                  ->    &ndash;

    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>

AUTHOR ^

Jason Burnett, <jason at jnj.org>

BUGS ^

Please report any bugs or feature requests to bug-text-wikicreole at rt.cpan.org, 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.

SUPPORT ^

You can find documentation for this module with the perldoc command.

    perldoc Text::WikiCreole

You can also look for information at:

ACKNOWLEDGEMENTS ^

The parsing algorithm is basically the same as (and inspired by) the one in Document::Parser. Document::Parser is OO and is, as such, incompatible with my brain.

COPYRIGHT & LICENSE ^

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.

syntax highlighting: