Author: Mark Buck (Kaivalagi) <m_buck@hotmail.com>

PREREQUISITES
=============

It is expected that the user is already familiar with Conky.

Any conky specific help can be found by either visiting the conky website here:

    http://conky.sourceforge.net

Alternatively there is a large user base, various helpful posts are available
at http://www.ubuntuforums.org

For example, to see various incarnations of conky setups, or to ask technical
questions you could go here:
    
        Post your .conkyrc files w/ screenshots

        http://ubuntuforums.org/showthread.php?t=281865 

If you are not familiar with conky there is help available here:

    HOW TO: A Beginners Guide to Setting up Conky

    http://ubuntuforums.org/showthread.php?t=867076

SCRIPTS WITHIN PACKAGE
======================

conkyText - provides formatted output from a delimited text file
conkyLatLong - provides latitude/longtitude co-ordinates based on your IP address
conkyDateDiff - provides a difference in time between now/a date to another date#
conkyDatetimeDiff - provides a difference in time between now/a datetime to another datetime with varying input and output formatting
conkyDaysDiff - provides a difference in days between now/a date to another date
conkySlideshow - provides a locally stored image on each call based on an input file of image URLs.

EXAMPLE USE
===========

In the /usr/share/conkymisc/example folder you'll a host of files named after
the scripts they serve to demonstrate

For example to test conkyText it can be run through Conky using these example files as follows:

    conky -c /usr/share/conkymisc/example/conkyText.conkyrc &


COMMAND OPTIONS
===============

Any scripts which have arguments will have detailed usage available by running
them with either the -h or --help switch.


For example running "conkyDatetimeDiff -h" gives this:

Usage: conkyDatetimeDiff [options]
Options:
  -h, --help            show this help message and exit
  -s DATETIME, --startdatetime=DATETIME
                        [Mandatory] Start datetime to use for difference
                        output
  -e DATETIME, --enddatetime=DATETIME
                        End datetime to use for difference output, if omitted
                        then the current datetime is used.
  -i FORMAT, --inputformat=FORMAT
                        default:[%Y%m%d]Specify the format of the input date
                        time fields. See python docs for formatting options:
                        http://docs.python.org/library/datetime.html#strftime-
                        and-strptime-behavior
  -o OPTION, --outputformat=OPTION
                        default:[DIFF]Specify the format of the output date
                        time difference values, options are either DIFF,
                        YEARS, MONTHS, WEEKS, DAYS, HOURS, MINUTES, SECONDS
  -S, --shortoutput     Specify if short output is required resulting in ':'
                        separated string values where complex or a number
                        where not rather than plain english
  -n, --displaynegatives
                        Specify if a negative value should be output, normally
                        only the positive time difference is displayed
  -v, --verbose         Request verbose output, not a good idea when running
                        through conky!
  --errorlogfile=FILE   If a filepath is set, the script appends errors to the
                        filepath.
  --infologfile=FILE    If a filepath is set, the script appends info to the
                        filepath.



And "conkyText -h" gives this:

Usage: conkyText [options]
Options:
  -h, --help            show this help message and exit
  -t FILE, --template=FILE
                        location of the template file to define the layout of
                        output
  -f FILE, --textfile=FILE
                        location of the text file to output.
  -d FILE, --delimiter=FILE
                        default:[;]Specify the delimiter to use when splitting
                        out a line of text into formatted segments
  -v, --verbose         Request verbose output, not a good idea when running
                        through conky!
  -V, --version         Displays the version of the script.
  --errorlogfile=FILE   If a filepath is set, the script appends errors to the
                        filepath.
  --infologfile=FILE    If a filepath is set, the script appends info to the
                        filepath.


And "conkyLatLong -h" gives this:

Usage: conkyLatLong [options]
Options:
  -h, --help            show this help message and exit
  -l, --longitudeonly   Force the script output Longitude only
  -L, --latitudeonly    Force the script output Latitude only
  -i, --imperial        Force the script to output in Degrees / Minutes and
                        Seconds. If not set the script outputs in the standard
                        metric decimal fashion
  -c NUMBER, --connectiontimeout=NUMBER
                        [default: 10]
  -v, --verbose         Request verbose output, not a good idea when running
                        through conky!
  -V, --version         Displays the version of the script.
  --errorlogfile=FILE   If a filepath is set, the script appends errors to the
                        filepath.
  --infologfile=FILE    If a filepath is set, the script appends info to the
                        filepath.


And "conkySlideshow -h" gives this:

Usage: conkySlideshow [options]
Options:
  -h, --help            show this help message and exit
  -t FILE, --template=FILE
                        location of the template file to define the layout of
                        output, the placeholders are [imagename], [imageurl]
                        and [imagepath]
  -l FILE, --imagelist=FILE
                        location of the text file providing the image list
                        data, strict format required of NAME;URL on each line.
  -i FILE, --index=FILE
                        [default: /tmp/conkySlideshow.idx] Location of the
                        temp index file used to store the last image index
                        used
  -o FILE, --output=FILE
                        [default: /tmp/conkySlideshow.jpg] Location of the
                        file used for output
  -r, --random          Request a random image from the list rather than the
                        next in the series
  -c NUMBER, --connectiontimeout=NUMBER
                        [default: 10]
  -v, --verbose         Request verbose output, not a good idea when running
                        through conky!
  --errorlogfile=FILE   If a filepath is set, the script appends errors to the
                        filepath.
  --infologfile=FILE    If a filepath is set, the script appends info to the
                        filepath.

ENJOY :)


