[cgi-wiki-dev] New feature for UseMod formatter

[Kate L Pugh]

I set up a wiki here at work but was berated for breaking our branding.
We are http://state51.co.uk/ and there is definitely no capital "s" allowed.

Now, CGI::Wiki::Formatter::UseMod forces node names in links to be
ucfirst, to avoid ending up with six home nodes called things like
"home", "Home", "HOME", etc.  Consistency is a good thing.

You can turn this munging off entirely, but you can't *partly* turn it
off.  I added an option to let you do some last-minute munging of the
node names, but I'm not sure I got the name right.  It's currently
called "munge_node_name" and its documentation is below.  Comments
ASAP please - I'd like to upload this as soon as PAUSE comes back.

Kake

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?',
                            node_suffix         => '',
                            edit_prefix         => 'wiki.pl?action=edit;id=',
                            edit_suffix         => '',
                            munge_urls          => 0,
             );

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

           Internal links
               "node_prefix", "node_suffix", "edit_prefix" and
               "edit_suffix" allow you to control the URLs gener-
               ated for links to other wiki pages.  So for exam-
               ple with the defaults given above, a link to the
               Home node will have the URL "wiki.pl?Home" and a
               link to the edit form for the Home node will have
               the URL "wiki.pl?action=edit;id=Home"
 
               (Note that of course the URLs that you wish to
               have generated will depend on how your wiki appli-
               cation processes its CGI parameters - you can't
               just put random stuff in there and hope it works!)
 
           Internal links - advanced options
               If you wish to have greater control over the
               links, you may use the "munge_node_name" parame-
               ter.  The value of this should be a subroutine
               reference.  This sub will be called on each inter-
               nal link after all other formatting and munging
               except URL escaping has been applied.  It will be
               passed the node name as its first parameter and
               should return a node name.  Note that this will
               affect the URLs of internal links, but not the
               link text.
 
               Example:
 
                 # The formatter munges links so node names are ucfirst.
                 # Ensure 'state51' always appears in lower case in node names.
                 munge_node_name => sub {
                                        my $node_name = shift;
                                        $node_name =~ s/State51/state51/g;
                                        return $node_name;
                                    }
 
               Note: This is advanced usage and you should only
               do it if you really know what you're doing.  Con-
               sider in particular whether and how your munged
               nodes are going to be treated by "retrieve_node".