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


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

In the /usr/share/conkygooglecalendar/example folder you'll find 2 files,
conkyrc and conkyGoogleCalendar.template

Conky can be run using these example files as follows:

    conky -c /usr/share/conkygooglecalendar/example/conkyrc &

HOWEVER the login details found in both files are invalid for obvious reasons.
I suggest looking at the files and making your own in your home folder based on
them. The call to conky would then need changing to suit the new path.

By running equivalent files with proper credentials you should see some output
at the top right of your screen.


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

A break down of all the options available are below. The same details can be
found by running conkyGoogleCalendar --help

Usage: conkyGoogleCalendar [options]
Options:
  -h, --help            show this help message and exit
  -u USERNAME, --username=USERNAME
                        Username for login into Google Calendar, this will
                        normally be your gmail account
  -p PASSWORD, --password=PASSWORD
                        Password to login with, if not set the username is
                        used to fetch a 'conky' password from the keyring
  -r TEXT, --requestCalendarNames=TEXT
                        Define a list of calendars to request event data for,
                        calendar names should be separated by semi-colons ";".
                        For example --requestCalendarNames="cal1;cal2;other
                        cal" If not set all calendar data will be returned.
  -d NUMBER, --daysahead=NUMBER
                        [default: 7] Define the number of days ahead you wish
                        to retrieve calendar entries for, starting from today.
  -s DATE, --startdate=DATE
                        Define the start date to retrieve calendar events. In
                        the form '2007-12-01'
  -e DATE, --enddate=DATE
                        Define the end date to retrieve calendar events, must
                        be supplied if --startdate supplied. In the form
                        '2007-12-01'
  -a, --allevents       Retrieve all calendar events
  -w TEXT, --wordsearch=TEXT
                        Define the text to search calendar entries with.
  -l NUMBER, --limit=NUMBER
                        [default: 0] Define the maximum number of calendar
                        events to display, zero means no limit.
  -t FILE, --template=FILE
                        Template file determining the format for each event.
                        Use the following placeholders: [title], [starttime],
                        [endtime], [completetime], [duration], [location],
                        [description], [who]. Ensure only one placeholder per
                        line, as the whole line is removed if no data for that
                        placeholder exists.
  -f "DATEFORMAT", --dateformat="DATEFORMAT"
                        If used this overrides the default date formatting.
                        The values to use are standard formatting strings e.g.
                        Weekday=%a, Day=%d, Month=%m, Year=%y. For an output
                        like "Thu 15/10/2008" you would require
                        --dateformat="%a %d/%m/%y", to have no date you would
                        require --dateformat=""
  -F "TIMEFORMAT", --timeformat="TIMEFORMAT"
                        If used this overrides the default time formatting.
                        The values to use are standard formatting strings e.g.
                        Hours (12hr)=%l, Hours (24hr)=%H, Minutes=%M,
                        Seconds=%S, AM/PM=%P. For an output like "05:22 PM"
                        you would require --timeformat="%l:%M %P",
                        --timeformat="" is not supported, default locale
                        settings are used
  -i NUMBER, --indent=NUMBER
                        [default: 0] Define the number of spaces to indent the
                        output (excludes template based output)
  -m NUMBER, --maxwidth=NUMBER
                        [default: 40] Define the number of characters to
                        output per line
  -n, --nowho           Hides who is attending the events (excludes template
                        based output)
  -c NUMBER, --connectiontimeout=NUMBER
                        [default: 30] Define the number of seconds before a
                        connection timeout can occur.
  -v, --verbose         Request verbose output, no 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.

TEMPLATE FILES
==============

A template file is included in the example files and there are also details on
the template option in the command options listed above.

Note that you are able to combine standard font output with other fonts in a 
single template, but must use either execp or execpi conky commands to do so.

Please take a look at the example template provided. You will see that it uses
text inside a "<" and a ">" as markers, these must be exact for the replacment
event text to be output. Anything outside of these markers will be output as
it looks in the template.

Note that it is advisable to only use one placeholder per line, as the whole
line in the template is removed from output if no data for that placeholder
exists.

FURTHER HELP
============

If you have an issue and are not sure, try running the same command in the
terminal window and add the option --verbose, you should then see lots of
information about what the script is doing, any warnings or errors should also
be displayed.

If after doing the above you are still stuck, further help can be found by 
visiting this thread on ubuntuforums.org:

	Conky Google Calendar Python Script
	
	http://ubuntuforums.org/showthread.php?t=837385

Note that it is best to post --verbose output of your script call, as well as
the conkyrc you are using. This way the issue can be understood quickly and
easily.

ENJOY :)


