NAME
    CGI::Wiki::Formatter::UseMod - UseModWiki-style formatting for CGI::Wiki

DESCRIPTION
    A formatter backend for CGI::Wiki that supports UseMod-style formatting.

SYNOPSIS
      use CGI::Wiki::Formatter::UseMod;

      # Instantiate - see below for parameter details.
      my $formatter = CGI::Wiki::Formatter::UseMod->new( %config );

      # Format some text.
      my $cooked = $formatter->format($raw);

      # Find out which other nodes that text would link to.
      my @links_to = $formatter->find_internal_links($raw);

      # UseModWiki "encodes" node names before making them part of a URL, so
      # for example a node about Wombat Defenestration will have a URL like
      #   http://example.com/wiki.cgi?Wombat_Defenestration
      # So if we want to emulate a UseModWiki exactly, we need to munge back
      # and forth between node names as titles, and node names as CGI params.
      my $node_param = $q->param('id') || $q->param('keywords') || "";
      my $node_name = $formatter->node_param_to_node_name( $node_param );

      use URI::Escape;
      my $url = "http://example.com/wiki.cgi?"
        . uri_escape(
           $formatter->node_name_to_node_param( "Wombat Defenestration" )
                     );

      # Yes, this is a bit of a pain, transparent ways to do this solicited.

METHODS
    new
          my $formatter = CGI::Wiki::Formatter::UseMod->new(
                         extended_links      => 0, # $FreeLinks
                         implicit_links      => 1, # $WikiLinks
                         force_ucfirst_nodes => 1, # $FreeUpper
                         use_headings        => 1, # $UseHeadings
                         allowed_tags        => [qw(b i)], # defaults to none
                         macros              => {},
                         node_prefix         => 'wiki.pl?',
                         edit_prefix         => 'wiki.pl?action=edit&id=' );

        Parameters will default to the values shown above (apart from
        "allowed_tags", which defaults to allowing no tags).

        Macros
            Be aware that macros are processed *after* filtering out
            disallowed HTML tags. They are also not called in any particular
            order.

            The keys of macros should be either regexes or strings. The
            values can be strings, or, if the corresponding key is a regex,
            can be coderefs. The coderef will be called with the first nine
            substrings captured by the regex as arguments. I would like to
            call it with all captured substrings but apparently this is
            complicated.

        Macro examples:

          macros => {

              '@SEARCHBOX' =>
                        qq(<form action="wiki.pl" method="get">
                           <input type="hidden" name="action" value="search">
                           <input type="text" size="20" name="terms">
                           <input type="submit"></form>),

              qr/\@INDEX\s+\[Category\s+([^\]]+)]/ =>
                    sub { return "{an index of things in category $_[0]}" }

          }

    format
          my $html = $formatter->format($submitted_content, $wiki);

        Escapes any tags which weren't specified as allowed on creation,
        then interpolates any macros, then translates the raw Wiki language
        supplied into HTML.

        A CGI::Wiki object can be supplied as an optional second parameter.
        This object will be used to determine whether a linked-to node
        exists or not, and alter the presentation of the link accordingly.
        This is only really in here for use when this method is being called
        from within CGI::Wiki.

    find_internal_links
          my @links_to = $formatter->find_internal_links( $content ); 
 
        Returns a list of all nodes that the supplied content links to.

    node_name_to_node_param
          use URI::Escape;
          $param = $formatter->node_name_to_node_param( "Recent Changes" );
          my $url = "wiki.pl?" . uri_escape($param);

        In usemod, the node name is encoded prior to being used as part of
        the URL. This method does this encoding (essentially, whitespace is
        munged into underscores). In addition, if "force_ucfirst_nodes" is
        in action then the node names will be forced ucfirst if they weren't
        already.

    node_param_to_node_name
          my $node = $q->param('node') || "";
          $node = $formatter->node_param_to_node_name( $node );

        In usemod, the node name is encoded prior to being used as part of
        the URL, so we must decode it before we can get back the original
        node name.

AUTHOR
        Kake Pugh (kake@earth.li).

COPYRIGHT
             Copyright (C) 2003 Kake Pugh.  All Rights Reserved.

        This module is free software; you can redistribute it and/or modify
        it under the same terms as Perl itself.

CREDITS
        The grubstreet team (<http://grault.net/grubstreet/>) sent some very
        helpful bug reports. A lot of the work of this module is done within
        chromatic's module, Text::WikiFormat.

CAVEATS
        This doesn't yet support all of UseMod's formatting features and
        options, by any means. (In particular, it doesn't cope with nested
        lists, but I think this might be something I need to fix within
        Text::WikiFormat.) This really truly *is* a 0.0* release. Please
        send bug reports, omissions, patches, and stuff, to me at
        "kake@earth.li".

        See <http://the.earth.li/~kake/cgi-bin/cgi-wiki/wiki.cgi> for a
        rough stab at a wiki that emulates the functionality as well as the
        formatting of a UseMod wiki. The source code is linked from there
        too.

SEE ALSO
        * CGI::Wiki
        * Text::WikiFormat
        * UseModWiki (<http://www.usemod.com/cgi-bin/wiki.pl>)