PLUGINS
=======

A plugin is a shared object that implements a set of callback functions.
To a user this essentially means that a plugin is a .so file that they
load inside of their golemrc file to add functionality to golem.  A few
plugins are included with this distribution; for instance, the root menus
are in a loaded plugin called simple_menus.

When loading a plugin from your rc file, it is convention that the plugin
be loaded from a seperate file that is included by the main rcfile.  For
instance, a plugin loading in a user's rcfile may look like this:

.include "plugins/box_iconify/rc"
.include "plugins/simple_menus/rc"

The included files can provide a tree-shaped data of name-value pairs to the
plugin it is going to load (which is the reason to seperate it from the main
golemrc). At any point in the load statement, you may either terminate it
with a semi-colon (;) or open a subparam block with { and }.  The following
examples should explain this better:

# example 1, just loading it
load "plugin_name";

# example 2, passing in two params
load "plugin_name" {
	param "text"  "heh";
	param "text2" "heh2";
	fileparam "test" "test.xpm";	# fileparam means to convert to a path
					# and is neccesary for any filename
					# parameter.
}

# example 3, passing in a tree of params
load "plugin_name" {
	param "text" "heh";
	param "tree" "tree" {
		param "asdf" "asdf";
		param "subtree" "subtree" { param "hehe" "haha"; }
	}
}

A good example of how this works in practice is too look at the sample
configuration file for the simple_menus plugin, which is included with this
distribution.

Plugins may also recieve parameters from forplug includes.  Forplug includes
are described in the file THEMES included with this distribution; and are
intended to allow themes to pass parameters such as pixmaps to plugins.