NAME
    CGI::Wiki::Kwiki - An instant wiki built on CGI::Wiki.

DESCRIPTION
    A simple-to-use front-end to CGI::Wiki. It can be used for several
    purposes: to migrate from a CGI::Kwiki wiki (its original purpose), to
    provide a quickly set up wiki that can later be extended to use more of
    CGI::Wiki's capabilities, and so on. It uses the Template Toolkit to
    allow quick and easy customisation of your wiki's look without you
    needing to dive into the code.

INSTALLATION
    The distribution ships with and installs a script called
    cgi-wiki-kwiki-install. Create an empty directory somewhere that your
    web server can see, and run the script. It will set up a SQLite
    database, install the default templates into the current directory, and
    create a cgi script to run the wiki. You now have a wiki - edit wiki.cgi
    to change any of the default options, and you're done.

MORE DETAILS
    wiki.cgi will look something like this:

      #!/usr/bin/perl -w
      use strict;
      use warnings;
      use CGI;
      use CGI::Wiki::Kwiki;

      my %config = (
        db_type => 'SQLite',
        db_name => '/home/wiki/data/node.db',
        formatters => {
                        default => 'CGI::Wiki::Formatter::Default',
                      },
      );

      my %vars = CGI::Vars();
      eval {
          CGI::Wiki::Kwiki->new(%config)->run(%vars);
      };

      if ($@) {
          print "Content-type: text/plain\n\n";
          print "There was a problem with CGI::Wiki::Kwiki:\n\n--\n";
          print "$@";
          print "\n--\n";
          print STDERR $@;
      }

    In the following directions, we use "webserver" to mean the user that
    your webserver executes CGI scripts as. Often this is actually you
    yourself; sometimes it is "www-data" or "apache". If you don't know, ask
    your ISP.

    In the script above and in the following, replace
    "/home/wiki/data/node.db" with a filename in a directory that you will
    be able to make readable and writeable by the webserver. SQLite requires
    access to both the file (for writing data) and the directory it resides
    in (for creating a lockfile).

    The above is a complete and absolutely minimal wiki CGI script. To make
    it work as-is:

    Set up the backend database
        This example uses DBD::SQLite, so make sure you have that installed.
        Then run the following command (which should have come with your
        CGI::Wiki install) to initialise an SQLite database:

          cgi-wiki-setupdb --type sqlite --name /home/wiki/data/node.db

        You should see notification of tables being created.

        Make sure that the webserver will be able to write to the database
        file and to the directory it lives in.

    Install the script and its templates
        Put the script somewhere suitable so that your webserver will
        execute it.

        Make a subdirectory of the directory the script is in, called
        "templates". Copy the templates from the CGI::Wiki::Kwiki tarball
        into this directory. The webserver will need to read from here but
        it doesn't need to be able to write.

    Set up a place for the searcher to index your wiki into
        Make a subdirectory of the directory the script is in, called
        "search_map". Make this writeable by the webserver.

    You can have all kinds of other fun with it though; see EXAMPLES below.
    In particular, a nicer formatter to use is CGI::Wiki::Formatter::UseMod.

METHODS
    new Creates a new CGI::Wiki::Kwiki object. Expects some options, most
        have defaults, a few are required. Here's how you'd call the
        constructor - all values here (apart from "formatters") are
        defaults; the values you must provide are marked.

            my $wiki = CGI::Wiki::Kwiki->new(
                db_type => 'MySQL',
                db_user => '',
                db_pass => '',
                db_name => undef,                     # required
                db_host => '',
                formatters => {
                    documentation => 'CGI::Wiki::Formatter::Pod',
                    tests         => 'My::Own::PlainText::Formatter',
                    discussion    => [
                                       'CGI::Wiki::Formatter::UseMod',
                                       allowed_tags   => [ qw( p b i pre ) ],
                                       extended_links => 1,
                                       implicit_links => 0,
                                     ],
                    _DEFAULT      => [ # if upgrading from pre-0.4
                                       'CGI::Wiki::Formatter::UseMod;
                                     ],
                              },                  # example only, not default
                site_name => 'CGI::Wiki::Kwiki site',
                admin_email => 'email@invalid',
                template_path => './templates',
                stylesheet_url => "",
                home_node => 'HomePage',
                cgi_path => CGI::url(),
                search_map => './search_map',
                prefs_expire => '+1M',    # passed to CGI::Cookie; see its docs
                charset => 'iso-8859-1', # characterset for the wiki
            );

        The "db_type" parameter refers to a CGI::Wiki::Store::[type] class.
        Valid values are 'MySQL', SQLite', etc: see the CGI::Wiki man page
        and any other CGI::Wiki::Store classes you have on your system.
        "db_user" and "db_pass" will be used to access this database.

        "formatters" should be a reference to a hash listing all the
        formatters that you wish to support. Different wiki pages can be
        formatted with different formatters; this allows you to do things
        like have documentation pages written in POD, test suite pages
        written in plain text, and discussion pages written in your
        favourite Wiki syntax. If this hash has more than one entry, its
        keys will be supplied in a drop-down list on every edit screen, and
        the selected one will be used when displaying that page.

        (If you *do* wish to supply more than one entry to the hash, you
        will need CGI::Wiki::Formatter::Multiple installed on your system.)

        Each value of the "formatters" hash can be either a simple scalar
        giving the class of the required formatter, or an anonymous array
        whose first entry is the class name and whose other entries will be
        passed through to the formatter instantiation, parsed as a hash.
        (See the "discussion" formatter entry in the example code above if
        this sounds confusing.)

        Note: Even if your "formatters" hash has only one entry, you should
        make its key be meaningful, since it will be stored in the node's
        metadata and will appear in dropdowns if you ever decide to support
        another kind of formatter.

        Backwards Compatibility Note: If you are upgrading from a version of
        CGI::Wiki::Kwiki earlier than 0.4, and you have an existing wiki
        running on it, you should supply a "_DEFAULT" entry in the
        "formatters" hash so it knows what to do with nodes that have no
        formatter metadata stored.

        This method tries to create the store, formatter and wiki objects,
        and will die() if it has a problem. It is the calling script's
        responsibility to catch any exceptions and tell the user.

    run Runs the wiki object, and outputs to STDOUT the result, including
        the CGI header. Takes no options.

            $wiki->run();

EXAMPLES
    Just for fun, here is the configuration part of the wiki script Kake
    uses at work, full of horrid little hacks. Kake is thoroughly ashamed of
    herself but feels this is worth showing around in case anyone
    accidentally gets a useful idea from it.

      #!/usr/bin/perl -w
      use strict;
      use warnings;
      use CGI;
      use CGI::Wiki::Formatter::UseMod;
      use CGI::Wiki::Kwiki;
      use CGI::Wiki::Store::SQLite;
      use LWP::Simple;

      # Set up an array of allowed tags so we can make a macro to show them.
      my @allowed_tags = qw( a b p i em tt pre img div code br );

      # Set up the formatter conf here since we will be setting up an extra
      # formatter in order to make links with some of the macros.
      my %formatter_conf = (
                             extended_links => 1,
                             implicit_links => 0,
                             allowed_tags => \@allowed_tags,
                             node_prefix => "index.cgi?node=",
                             edit_prefix => "index.cgi?action=edit;node=",
                             # branding is important
                             munge_node_name => sub {
                                 my $node_name = shift;
                                 $node_name =~ s/State51/state51/g;
                                 $node_name = "alex" if $node_name eq "Alex";
                                 return $node_name;
                             },
                           );
      my $formatter = CGI::Wiki::Formatter::UseMod->new( %formatter_conf );
      # Create an extra wiki object too for passing to ->format when we call
      # it in the macros - so the formatter can find out which nodes already
      # exist.
      my $wiki = CGI::Wiki->new(
          store => CGI::Wiki::Store::SQLite->new(
                                              dbname => "./data/node.db"
                                                )
                               );

      my %macros = (
          # Perl Advent Calendar feed
          '@PERL_ADVENT_TODAY' => sub {
              my $xml = get( "http://perladvent.org/perladventone.rdf" )
                or return "[Can't get RSS for the Perl Advent Calendar!]";
              # Yes I know parsing XML with regexes is yuck, but this
              # is just a quick hack for December.
              if ( $xml =~ m|<item>\s*<title>([^<]+)</title>\s*<link>([^<]+)</link>| ) {
                  return qq(<div align="center" style="border:dashed 1px; padding-top:5px; padding-bottom:5px;">Today's Perl Advent Calendar goodie is: [<a href="$2">$1</a>]</div>);
              } else {
                  return "Can't parse Perl Advent Calendar RSS!";
              }
          },

          # Match state51::* modules and link to wiki page.
          qr/\b(state51::\w+(::\w+)*)\b/ => sub {
              my $module_name = shift;
              my $link = $formatter->format( "[[$module_name]]", $wiki );
              $link =~ s|<p>||;
              $link =~ s|</p>||;
              chomp $link; # or headings won't work
              return "<tt>$link</tt>";
          },

          # Match non-state51::* modules and link to search.cpan.org.
          # Don't match anything already inside an <a href ...
          # or preceded by a :, since that will be part of state51::*
          qr/(?<![>:])\b([A-Za-rt-z]\w*::\w+(::w+)*)\b/ => sub {
              my $module_name = shift;
              my $dist = $module_name;
              $dist =~ s/::/-/g;
              return qq(<a href="http://search.cpan.org/dist/$dist"><tt><small>(CPAN)</small> $module_name</tt></a>);
          },

          # Print method names in <tt>
          qr/(->\w+)/ => sub { return "<tt>$_[0]</tt>" },

          # Macro to list available HTML tags.
          '@ALLOWED_HTML_TAGS' => join( ", ", @allowed_tags ),
      );

      my %config = (
          db_type => 'SQLite',
          db_name => './data/node.db',
          db_user => 'not_used',
          home_node => "Home",
          site_name => "state51 wiki",
          formatters => {
                          default => [
                                       'CGI::Wiki::Formatter::UseMod',
                                        %formatter_conf,
                                        macros => \%macros,
                                     ]
                        },
          template_path => "templates/",
          search_map => "./data/search_map/",
      );

    The above is not intended to exemplify good programming practice.

TODO
    Things I still need to do

    Polish templates
    Import script should catch case-sensitive dupes better
    CGI::Wiki::Kwiki does not currently work under mod_perl. This is a
    serious problem. =back

SEE ALSO
        *   CGI::Wiki

        *   <http://london-crafts.org> - a wiki for a local crafts group,
            running on CGI::Wiki::Kwiki

AUTHORS
        Tom Insam (tom@jerakeen.org) Kake Pugh (kake@earth.li)

CREDITS
        Thanks to Kake for writing CGI::Wiki, and providing the initial
        patches to specify store and formatter types in the config. And for
        complaining at me till I released things. Thanks to Ivor Williams
        for diff support.

COPYRIGHT
             Copyright (C) 2003-2004 Tom Insam.  All Rights Reserved.

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

