NAME

Text::KwikiFormatish - convert Kwikitext into XML-compliant HTML

SYNOPSIS

  use Text::KwikiFormatish;
  my $xhtml = Text::KwikiFormatish::format($text);

DESCRIPTION

NOTE: This module is based off of the old CGI::Kwiki formatter. Ideally, Text::KwikiFormat would be written to use the new the new Kwiki formatter.

CGI::Kwiki includes a formatter (CGI::Kwiki::Formatter) for converting Kwikitext (a nice form of wikitext) to HTML. Unfortunately, it isn't easy to use the formatter outside the CGI::Kwiki environment. Additionally, the HTML produced by the formatter isn't XHTML-1 compliant. This module aims to fix both of these issues and provide an interface similar to Text::WikiFormat.

Essentially, this module is the code from Brian Ingerson's CGI::Kwiki::Formatter with a format subroutine, code relating to slides removed, tweaked subroutinesa, and more.

Since the wikitext spec for input wikitext for this module differs a little from the default Kwiki formatter, I thought it best to call it "Formatish" instead of *the* Kwiki Format.

format()

format() takes one or two arguments, with the first always being the wikitext to translate. The second is a hash of options, but currently the only option supported is prefix in case you want to prefix wiki links with sommething. For example,

  my $xml = Text::KwikiFormatish::format(
    $text,
    prefix => '/wiki/',
  );

EXTENDING

CGI::Kwiki::Formatter was designed to be subclassable so that the formatting engine could be easily customized. Information on how the Kwiki formatter works can be found at HowKwikiFormatterWorks.

For example, say you wanted to override the markup for strong (bold) text. You decide that it would make much more sense to write strong text as HEYthis is bold textHEY. You would subclass Text::KwikiFormatish and use it like so:

    package My::Formatter;
    use base 'Text::KwikiFormatish';
    
    # I simply copied this from Text/KwikiFormatish.pm and tweaked it
    sub bold {
        my ($self, $text) = @_;
        $text =~ s#(?<![$WORD])HEY(\S.*?\S|\S)HEY(?![$WORD])#<strong>$1</strong>#g;
        return $text;
    }
    
    package main;
    my $data = join '', <>;
    print My::Formatter->new->process( $data );

Administrative Methods

process( TEXT )

Process the given TEXT as KwikiText and return XHTML.

process_order()

process_order() returns a list of the formatting rules that will be applied when format is called for this object. If called with a set of formatting rules (names of class methods), that set of formatting rules will supercede the default set.

* new() - the constructor

* init() - called by the constructor immediately after the objects creation

Helper Methods

• split_method( TEXT, REGEXP, METHOD ) - calls METHOD on any matches in TEXT for groups in REGEXP

• escape_html( TEXT ) - returns TEXT with HTML entities escaped

Formatter Methods

These are the methods you'll probably override most often. They define the regular expressions that the formatter uses to split text as well as what to do with each chunk.

Many of these methods have corrosponding format_xxx methods, which take the chunk and format it as XHTML.

• function - user-definable functions

• table - tabular data

• format_table - format the table data as XHTML

• no_wiki_link - things that look like wikilinks but are forced not to be

• no_wiki_link_format - typically just the text that could have been a link

• wiki_link - a WikiLink

• force_wiki_link - a link that normally wouldn't have been one but is forced to be

• wiki_link_format - how to format wikilinks as XHTML

• no_http_link - what normally would have been an HTTP URI, but isn't

• no_http_link_format - typically just the text

• http_link - a regular http:// hyperlink

• http_link_format - how to format the given link

• no_mailto_link - what could have been a mailto: hyperlink

• no_mailto_link_format - typically just text

• mailto_link - a mailto: hyperlink

• mailto_link_format - how to format the mailto: link

• img_format - inline images

• link_format - a helper method for named_http_link_format and http_link_format

• named_http_link - an HTTP URI with a label

• named_http_link_format - how to format the named link

• inline - code samples or fixed-width font, usually

• inline_format - how to format inline markup

• negation - when not to make an inline format

• bold - strong text

• italic - emphasized text

• underscore - if you reall, really, really feel the need to use underlined text

• code - usually indented text creates blocks of preformatted text

• code_format - how to format the code blocks

• lists - itemized or enumerated lists

• lists_format - how to format the lists

• paragraph - normal, boring paragraphs

• paragraph_format - how to format paragraphs as XHTML

• horizontal_line - horizontal rules

• horizontal_line_format - horizontal rules as XHTML

• mdash - long horizontal dashes

• comment - text that doesn't show up in the final markup

• comment_line_format - make XML comments out of 'em

• header_N and header_N_format - where N is a number from 1 to 6, inclusive

Adding User Functions

• user_functions() - returns a list of custom markup plugins to handle

  The default user functions are icon, img and glyph. In the default markup, plugins are entered in the form of [&name arg1 arg2 ...].

• icon - inserts the named image with a CSS class of "icon"

      [&icon /icons/fun.png]

• img - inserts a regular image, with an optional title

      [&img some_image.jpg]
  
      [&img another_image.jpg This image will have a title attribute]

• glyph - attempts to insert an image that's aligned with the vertical middle of the text, but doesn't work due to the implementation of the parser

DIFFERENCES FROM THE CGI::KWIKI FORMATTER

• The output of the formatter is XML-compliant.

• Extra equal signs at the end of headings will be removed from the output for compatibility with other wikitext formats.

• Italicized text is marked up by two slashes instead of one. This is to prevent weirdness when writing filesystem paths in Kwikitext -- e.g., the text "Check /etc or /var or /usr/" will have unexpected results when formatted in a regular Kwiki.

• Horizontal rules, marked by four or more hyphens, may be followed by spaces.

• Processing order of text segments has been changed (tables are processed last)

• Bold text is marked up as <strong> instead of <b>

• "Inline" is marked up as <code> instead of <tt>

• mdashes (really long hyphens) are created with wikitext like---this

• Tables and code sections are not indented with <blockquote> tags

• Comments do not have to have a space immediately following the hash

• Patch to named_link code

• All code pertaining to slides or Kwiki access control is removed, as neither are within the scope of this module

Plugins

I've included two plugins, img and icon, to do basic image support besides the standard operation of including an image when the URL ends with a common image extension.

EXAMPLES

Here's some kwiki text. (Compare with KwikiFormattingRules.)

    = Level 1 Header
    
    == Level 2 with optional trailing equals ==
    
    Kwikitext provides a bit more flexibility than regular wikitext.
    
    All HTML code is <escaped>. Horizontal rules are four or more hyphens:
    
    ----
    
    While you can add an mdash---like this.
    
    ##
    ## you can add comments in the kwikitext which appear as XML comments
    ##
    
    == Links
    
    === Itemized Lists
    
    * Fruit
    ** Oranges
    ** Apples
    * Eggs
    * Salad
    
    === Enumerated Lists
    
    ##
    ## below are zero's, not "oh's"
    ##
    
    0 One
    0 Two
    0 Three
    
    * Comments in the wikitext
    * Easier:
    ** Bold/strong
    ** Italic/emphasized
    
    == More Markup
    
    *strong or bold text*
    
    //emphasized or italic text//
    
      indented text is verbatim (good for code)
    
    == Links
    
    WikiLink
    
    !NotAWikiLink
    
    http://www.kwiki.org/
    
    [Kwiki named link http://www.kwiki.org/]
    
    == Images
    
    http://search.cpan.org/s/img/cpan_banner.png
    
    == KwikiFormatish plugins
    
    This inserts an image with the CSS class of "icon" -- good for inserting a right-aligned image for text to wrap around.
    
    [&icon /images/logo.gif]
    
    The following inserts an image with an optional caption:
    
    [&img /images/graph.gif Last Month's Earnings]

AUTHOR

Maintained by Ian Langworth - ian@cpan.org

Based on CGI::Kwiki::Formatter by Brian Ingerson.

Thanks to Jesse Vincent for the process_order patch, related documentation and testing.

Additional thanks to Mike Burns, Ari Pollak and Ricardo SIGNES for additional testing.

SEE ALSO

CGI::Kwiki, CGI::Kwiki::Formatter, Text::WikiFormat

LICENSE

This is free software. You may use it and redistribute it under the same terms as perl itself.

cpanm Text::KwikiFormatish

perl -MCPAN -e shell
install Text::KwikiFormatish