#!perl -w
# run this document through perl to check its syntax
use Pod::Checker;
podchecker(\*DATA);
__END__

=head1 NAME

HOWTO-Plugins - How to write and use Slash plugins

=head1 QUESTIONS

=head2 What is a plugin?

A plugin is an extension to the Slash system
that adds some sort of functionality to
the site. It should inherit its basic look
and feel from the currently running theme
(for example, background/foreground colors, calling
header and footer components, etc. will be handled
by the installed theme).

=head2 How do I get my plugin into the install system?

There are two ways to do this. First, you can put it in the
plugins directory with the distribution. During the install it
will be copied to the plugins directory in (by default,
F</usr/local/slash/plugins/>. The second option is to copy it in
there yourself and make sure that your library files (perl modules)
are installed. If you decide to go the first route you
may want to consider adding your libraries to the list
of plugins that get installed, in the main Slash Makefile.

=head2 What does my plugin need to make it work with the install?

If you look at the plugins that come with Slash you will find a 
file called PLUGIN. This handles how the plugin installer will
see your plugin.  In the file, each keyword appears on a line
by itself with a '=' seperating it and the directive.  For example:

	htdoc=search.pl

The following are the keywords it knows:

=over 4

=item description

What will be displayed during the install for the user,
describing what the plugin does

=item mysql_schema

Schema for MySQL

=item mysql_dump

Dump for MySQL

=item pg_schema

Schema for PostgreSQL

=item pg_dump

Dump for PostgreSQL

=item htdoc

A document to be installed in the htdocs directory for the Slash site

=item template

A template to be installed in the database

=item image

An image to be installed in the image directory

=item note

A note to show the user when the install is over.
Good place to put notes about aditional libraries
needed, or other dependencies.

=back

=head2 How do I install a plugin once my site is installed?

Use the install-plugin tool. If run with the C<-h> option,
it will describe the tool's usage.  If can list available
plugins and you can then select which plugins you want to
install (just like with install-slashsite).

=head2 Do install-plugin and install-slashsite use the same logic?

Yes, you can find it in the Slash::Install library.

=head2 I have a really cool plugin and I would like to see it added to the Slash distribution. Will you distribute mine?

Maybe. We don't have any rules concerning this at the moment, so it will be
on a case by case basis. At some point in the future we will come up
with a much better answer.

=head1 VERSION

$Id$