Add documentation for plugins

diff --git a/videosite/readme.txt b/videosite/readme.txt
new file mode 100644 (file)
index 0000000..943e430
--- /dev/null
+++ b/videosite/readme.txt
@@ -0,0 +1,162 @@
+There are two different kind of plugins in this directory:
+grabbers and getters.
+
+Grabbers
+========
+
+The job of the Grabbers is to determine the download URL of the
+actual media file we want to get (in case of flash video sites
+that means to find out the URL which contains the actual flash
+video file, in contrast to the URL of the page where the flash
+plugin is embedded in).
+
+All Grabbers inherit from GrabberBase, which defines some methods
+shared by all Grabbers.
+
+In order to be loaded, a Grabber module must be named *Grabber.pm
+(i.e., the file name of the module must end with Grabber.pm).
+
+
+Methods
+-------
+
+get(line):
+This method is called for each of the installed grabbers, in turn
+(there is no guaranteed order for this) for each line received by
+irssi in any channel you are connected to.
+
+If the Grabber determines that a URL it can handle is mentioned in
+this line it is supposed to determine the metadata hash (more of this
+later) and return it. If the Grabber does not think the line interesting
+it returns undef, and the line is passed to the next Grabber.
+
+Note:
+Usually, you do _not_ need to overload this method in your Grabber.
+The default method looks for a property called 'PATTERNS' in your
+Grabber and treats this as an array reference, containing regex patterns
+matching the URLs the Grabber is interested in. If one of these patterns
+matches line, the method _parse is called like this:
+return $self->_parse(line, pattern);
+
+If you define your own Grabber, overload _parse instead, unless you
+want a totaly different approach.
+
+
+Properties
+----------
+
+NAME:
+A name for your Grabber. Has to be unique among all Grabbers and Getters
+installed.
+
+PATTERNS:
+See the description for get() under Methods.
+
+
+Getters
+=======
+
+The job of a Getter is to actually download a media file, the metadata of
+which has been determined by a Grabber.
+
+All Getters inherit from GetterBase, which defines some methods shared by all
+Getters.
+
+In order to be loaded, a Getter module must be named *Getter.pm
+(i.e., the file name of the module must end with Getter.pm).
+
+
+Methods
+-------
+
+get(metadata):
+This method is called with a metadata hash containing the data of a file that
+is to be downloaded. See below for a description of the content of the hash.
+
+The implementation of the actual download method is entirely left to the
+Getter. The Getter should return 1 on success, and 0 on failure.
+
+
+Properties
+----------
+
+NAME:
+A name for your Getter. Has to be unique among all Getters and Grabbers
+installed.
+
+
+The Metadata
+============
+
+The Metadata is a hash describing various properties of a media file to be
+downloaded. A Grabber produces a Metadata hash if it has found an URL of
+interest and was able to determine all data necessary to download the media
+file. The Metadata is then passed to a Getter, which uses the data to
+download the file and give it a recognizable name. The Metadata should
+(at least) contain the following fields:
+
+TITLE:
+A short, textual description of the file, usually taken from the site the
+file was taken from.
+
+ID:
+A number or string describing the file in the context of the site the file is
+from. This is usually unique for a single site, but does not have to be across
+different sites (or, in other words, the tuple [ID, SOURCE] should be unique)
+
+SOURCE:
+A short string describing the site the file is from. Should be a single word,
+like 'youtube' or '4chan'.
+
+URL:
+The URL of the site the media file was embedded in (this is usually the URL
+that was accepted and parsed by the Grabber).
+
+DLURL:
+The URL of the actual media file. This is the file that should be downloaded
+by the Getter.
+
+TYPE:
+A short string describing the nature of the media file. Should be a single
+word, like 'video' or 'image'.
+
+
+
+Parameters
+==========
+
+If you want your Grabber or Getter to have user settable parameters, which are
+saved across different runs of the plugin you can use the built-in parameter
+handling, which will take care of automagically saving and loading your
+parameters.
+
+In order to use it three steps are necessary:
+
+a) in your constructor, define a property called '_PARAMS'. This is a
+reference to a hash of array references, tke key being the name of your
+parameter, and the array containing the default value of the parameter as the
+first field, and a textual description string as the second field.
+
+For example, a parameter called FOO, having a default value of 42 and a
+description of 'This is the FOO parameter, twiddle it to do stuff' would be
+declared as follows:
+
+sub new {
+    my $class = shift;
+    my $self = $class->SUPER::new();
+
+    $self->{'_PARAMS'} = {'FOO' => [42, 'This is the FOO parameter, twiddle it to do stuff']};
+    bless($self, $class);
+    $self->_prepare_parameters();
+
+    return $self;
+}
+
+b) as seen in the example above, after declaring the parameter hash, call the
+method _prepare_parameters() on your class instance. This will convert the
+hash into the internally used data structure and prepare it for automatic
+loading and saving.
+
+c) to access one of the parameters, call the _getval() method, giving the name
+of the parameter as first argument. This will return the current value of that
+parameter (either the default value or the user defuned value).