$Id: README,v 1.22 2004/12/14 02:24:55 kevin Exp $

Author: Kevin Walsh <kevin@cursor.biz>

Copyright (c) 2003 Cursor Software Limited.
All rights reserved.

Plug-in modules for the SlimServer.


Manifest
--------

The following files are included in this archive:

    LICENSE             The text of the GNU GPL license.
    README              This file.

    BBCNews.pm          BBC News headlines.
    Blackjack.pm        Blackjack card game.
    Calculator.pm       Calculator.
    Information.pm      SlimServer, player, library and module information.
    MaximumEdgeNews.pm  News headlines from www.maximumedge.com.
    PhoneBook.pm        Simple phone book.
    RecentlyPlayed.pm   Allows the user to browse the tracks that have been
                        played recently.
    TopHits.pm          Allows the user to browse the most popular tracks in
                        the jukebox.
    WorldTime.pm        World time.

    maximumedge_update.pl
                        Support file for the MaximumEdge News plug-in - gathers
                        the news text.  Not required if "live" lookups have
                        been configured.
    news_mirror.pl      Support file for the BBC News plug-in - gathers the
                        news text.  Not required if "live" lookups have been
                        configured.


NOTE:  The Statistics.pm and PluginInfo.pm files have been removed from
this archive;  The code from those modules has been incorporated into the
greatly-expanded Plugins::Information module.


Prerequisites
-------------

The following files require the listed Perl module(s) to be installed
and operational in addition to the modules supplied with the SlimServer
software:

    Calculator.pm           Math::BigFloat
    maximumedge_update.pl   LWP::UserAgent
    news_mirror.pl          LWP::UserAgent

All of the Perl modules require version 6.0.0 (or later) of the SlimServer
software.

Note that some of these modules may not display correctly on the new
graphical SqueezeBox.


Installation
------------

Place the modules in your SlimServer Plugins directory and restart the
SlimServer daemon.  The modules should be recognised immediately and made
available in the 'Extras' section of your client menu.

Install the prerequsite Perl modules, listed above, for each of the files
you want to install.

UNIX/Linux users would simply type the following:

    perl -MCPAN -e 'install modulename'

Where modulename is something like LWP::UserAgent, for instamce.

MS Windows users who are using the binary version of the SlimServer
have more work to do, but that's a punishment for not supporting open
source operating systems and source code freedom in general. :-)


Configuration
-------------

Some of the modules have configurable settings.  See the comments in
the modules for more information.

Noteably, the BBCNews module can be made to read news either from a
HTTP URI or from a text file.  If the text file lookup is configured,
as is the default, then you will need to run the supplied news_mirror.pl
script periodically in order to keep the news file up to date.  The
news_mirror.pl script has configurable options, such as the location
of the SlimServer home directory, the HTTP URI to contact to gather the
news and an optional $proxy setting to tell the mirror to contact the
remote URI via a HTTP proxy server.

If you are a MS Windows user then DO NOT edit these modules with an editor
that is unsuitable for the job.  Most Windows-based file editors, such as
Notepad and Wordpad etc., fill files with junk characters, such as a CR at
the end of every line.  I understand that UltraEdit and textpad are two of
the editors that respect file formats and only make the changes you ask,
although I have no way to verify this.  Basically, if you're a MS Windows
user then you have four choices:  (1) find a proper editor that works with
your O/S (2) don't edit these modules (3) don't download and use these
modules, or (4) get a real operating system, such as UNIX or Linux, that
comes with with a selection of working editors as standard.


Internationalisation
--------------------

Each of the modules has a __DATA__ section at the end of the file.
The __DATA__ section is made up of a number of string tokens followed
by translation text for various languages.  "EN" stands for English and
there are various other language tokens available.  Edit the __DATA__
section as you see fit, or move the data to your SlimServer's "strings.txt"
file.