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

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=',
                         munge_urls          => 0,
          );

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

        URL munging
            If you set "munge_urls" to true, then your URLs will be more
            user-friendly, for example

              http://example.com/wiki.cgi?Mailing_List_Managers

            rather than

              http://example.com/wiki.cgi?Mailing%20List%20Managers

            The former behaviour is the actual UseMod behaviour, but
            requires a little fiddling about in your code (see
            "node_name_to_node_param"), so the default is to not munge URLs.

        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.

        Note that unless "munge_urls" was set to true when "new" was called,
        this method will do nothing.

    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.

        Note that unless "munge_urls" was set to true when "new" was called,
        this method will do nothing.

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 OpenGuides London team (<http://openguides.org/london/>) 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".

NOTE ON USEMOD COMPATIBILITY
        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 $formatter = CGI::Wiki::Formatter::UseMod->new( munge_urls => 1 );
          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" )
                         );

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