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/conkyforecast/example folder you'll find 8 files, providing 3
different examples of font and image based output, the list of files are:

conkyForecast.fontbased.conkyrc
conkyForecast.fontbased.sh
conkyForecast.fontbasedtemplate.conkyrc
conkyForecast.fontbasedtemplate.sh
conkyForecast.fontbasedtemplate.template
conkyForecast.imagebasedtemplate.conkyrc
conkyForecast.imagebasedtemplate.sh
conkyForecast.imagebasedtemplate.template

Note that the .sh files when run through a shell will display that particular
example. For more on how they work open the files and take a look!

By running this you should see some output at the top right of your screen, 
detailing all sorts of weather information.

If you wish to use these example files for your own creations it would be best
to copy the files to your $HOME location and edit them appropriately.

TESTING
=======

In the /usr/share/conkyforecast/test folder you'll find 3 files, providing for
test output, these files are:

conkyForecast.test.conkyrc
conkyForecast.test.sh
conkyForecast.test.conkyrc

Note that the .sh file when run through a shell will display the test window.
For more on how they work open the files and take a look!

By running this you should see some output in a conky dialog, detailing all
sorts of weather information. This is a test script for use with new releases.


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

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

Usage: conkyForecast [options]
Options:
  -h, --help            show this help message and exit
  -C FILE, --config=FILE
                        [default: ~/.conkyForecast.config] The path to the
                        configuration file, allowing multiple config files to
                        be used.
  -l CODE, --location=CODE
                        location code for weather data [default set in
                        config]. Use the following url to determine your
                        location code by city name:
                        http://xoap.weather.com/search/search?where=Norwich
  -d DATATYPE, --datatype=DATATYPE
                        [default: HT] The data type options are: DW (Day of
                        Week), WF (Weather Font output), WI (Weather Icon
                        Path), LT (Forecast:Low Temp,Current:Feels Like Temp),
                        HT (Forecast:High Temp,Current:Current Temp), CC
                        (Current Conditions), CT (Conditions Text), PC
                        (Precipitation Chance), HM (Humidity), VI
                        (Visibility), WD (Wind Direction), WA (Wind Angle - in
                        degrees), WS (Wind Speed), WG (Wind Gusts), BF
                        (Bearing Font), BI (Bearing Icon Path), BS (Bearing
                        font with Speed), CN (City Name), CO (Country), OB
                        (Observatory), SR (SunRise), SS (SunSet), DL
                        (DayLight), MP (Moon Phase), MF (Moon Font), MI (Moon
                        Icon Path), BR (Barometer Reading), BD (Barometer
                        Description), UI (UV Index), UT (UV Text), DP (Dew
                        Point), WM (weather map fetch and image path
                        returned),  LU (Last Update at weather.com), LF (Last
                        Fetch from weather.com). Not applicable at command
                        line when using templates.
  -s NUMBER, --startday=NUMBER
                        define the starting day number, if omitted current
                        conditions are output. Not applicable at command line
                        when using templates.
  -e NUMBER, --endday=NUMBER
                        define the ending day number, if omitted only starting
                        day data is output. Not applicable at command line
                        when using templates.
  -S NUMBER, --spaces=NUMBER
                        [default: 1] Define the number of spaces between
                        ranged output. Not applicable at command line when
                        using templates.
  -t FILE, --template=FILE
                        define a template file to generate output in one call.
                        A displayable item in the file is in the form
                        [--datatype=HT --startday=1]. The following are
                        possible options within each item: --location,--
                        datatype,--startday,--endday,--night,--shortweekday,--
                        imperial,--beaufort,--metrespersecond,--hideunits,--
                        hidedegreesymbol,--spaces,--minuteshide. Note that the
                        short forms of the options are not supported! If any
                        of these options is set from the commandline, it sets
                        the default value of the option for all template
                        items.
  -L LOCALE, --locale=LOCALE
                        override the system locale for language output
                        (bg=bulgarian, cs=czech, de=german, es=spanish,
                        en=english, es=spanish, fj=fijian, fr=french,
                        it=italian, nl=dutch, pl=polish, ro=romanian,
                        sk=slovak, more to come)
  -i, --imperial        request imperial units, if omitted output is in
                        metric.
  -b, --beaufort        request beaufort scale for wind speeds, if omitted
                        output is either metric/imperial.
  -M, --metrespersecond
                        request metres per second for wind speeds, if omitted
                        output is either metric/imperial.
  -n, --night           switch output to night data, if omitted day output
                        will be output.
  -w, --shortweekday    Shorten the day of week data type to 3 characters.
  -u, --hideunits       Hide units such as mph or C, degree symbols (°) are
                        still shown.
  -x, --hidedegreesymbol
                        Hide the degree symbol used with temperature output,
                        this is only valid if used in conjunction with
                        --hideunits.
  -m NUMBER, --minuteshide=NUMBER
                        Works only with LU and LF. If present, hides the date
                        part of the LU or LF timestamp if the day of the
                        timestamp is today. The time part is also hidden, if
                        the timestamp is older than minutes specified in this
                        argument. If set to 0, the time part is always shown.
                        If set to -1, the value EXPIRY_MINUTES from the config
                        file is used.
  -c WIDTH, --centeredwidth=WIDTH
                        If used the output will be centered in a string of the
                        set width, padded out with spaces, if the output width
                        is greater than the setting it will be truncated
  -r, --refetch         Fetch data regardless of data expiry.
  -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.



FONTS
=====

There are several fonts included in the release, these are installed to /usr/share/fonts/truetype/conkyforecast

They should be used as follows:

    * ConkyWeather - should be used in conjunction with the WF (weather font)
      datatype
    * Arrows - can used in conjunction with the BF (bearing font) datatype,
      to display a simeple wind direction arrow
    * ConkyWind, ConkyWindN and ConkyWindNESW - should be used in conjunction
      with either the BF (bearing font) or BS (bearing font with speed) datatype
    * Moon Phases - should be used in conjunction with the MF (moon font)
      datatype


CONFIG SETTINGS
===============

A template config file exists which holds all the settings used by the script,
and most importantly, stores the partner id and registration code for the
weather.com xoap service.

It can be found here "/usr/share/conkyforecast/conkyForecast.config"

For a working script you NEED to define, in user specific config file, a
partner id and registration code for the weather.com xoap service. For this
purpose the config file should be copied to "~/.conkyForecast.config" and
setup as required.

To copy and edit the config, using the command line , run the following two
commands in a terminal:

    cp /usr/share/conkyforecast/conkyForecast.config ~/.conkyForecast.config
    nano ~/.conkyForecast.config

More details on the xoap service registration, including how to register to
obtain the required keys, is below in the XOAP_PARTNER_ID and
XOAP_REGISTRATION_KEY config setting details.

Below is a breakdown of all the settings and their purpose.

  CACHE_FOLDERPATH = /tmp/
    
    This setting dictates where the "pickled" weather data is cached for
    further use by the script. There will be one pickled file per location with
    the name .conkyForecast-LOCATION.cache, with LOCATION replace with your
    used location codes.
    
    Pickling the information retrieved means that it can be reused without
    needing a round trip to the weather.com XOAP service each time something is
    displayed through a script call.

    The default folder used is /tmp which is fine in most cases. However it
    should be noted that the /tmp folder is emptied on reboot, so data will
    not be kept in this case and a will needs refetching from the web again.

    In situations where reboots are common, you could change the path to your
    own home folder if desired, meaning that cached data will never be lost.


  CONNECTION_TIMEOUT = 5

    This setting is just that, it defines the timeout period for the connection
    establishment. This setting probably will not need changing, however with
    poor connectivity a higher value may be required.


  EXPIRY_MINUTES = 30

    This setting defines how long the cached weather data remains valid for.
    When the script is called, if the datetime of the cached files is older
    than this setting in minutes, the script will refetch the weather data
    required, and refresh the cache.


  TIME_FORMAT = %H:%M
  DATE_FORMAT = %Y-%m-%d

    These settings define the formatting of both date and datetime output.
    They follow standard strftime formatting conventions and are listed below.

    +=======================================================================+
    | Value | Result                                                        |
    |=======================================================================|
    |  %a   | Locale's abbreviated weekday name.                            |
    ------------------------------------------------------------------------|
    |  %A   | Locale's full weekday name.                                   |
    ------------------------------------------------------------------------|
    |  %b   | Locale's abbreviated month name.                              |
    |-----------------------------------------------------------------------|
    |  %B   | Locale's full month name.                                     |
    ------------------------------------------------------------------------|
    |  %c   | Locale's appropriate date and time representation.            |
    ------------------------------------------------------------------------|
    |  %d   | Day of the month as a decimal number [01,31].                 |
    ------------------------------------------------------------------------|
    |  %H   | Hour (24-hour clock) as a decimal number [00,23].             |
    ------------------------------------------------------------------------|
    |  %I   | Hour (12-hour clock) as a decimal number [01,12].             |
    ------------------------------------------------------------------------|
    |  %j   | Day of the year as a decimal number [001,366].                |
    ------------------------------------------------------------------------|
    |  %m   | Month as a decimal number [01,12].                            |
    ------------------------------------------------------------------------|
    |  %M   | Minute as a decimal number [00,59].                           |
    ------------------------------------------------------------------------|
    |  %p   | Locale's equivalent of either AM or PM.                       |
    ------------------------------------------------------------------------|
    |  %S   | Second as a decimal number [00,61].                           |
    ------------------------------------------------------------------------|
    |  %U   | Week number of the year (Sunday as the first day of the week) |
    |       | as a decimal number [00,53]. All days in a new year preceding |
    |       | the first Sunday are considered to be in week 0.              |
    ------------------------------------------------------------------------|
    |  %w   | Weekday as a decimal number [0(Sunday),6].                    |
    ------------------------------------------------------------------------|
    |  %W   | Week number of the year (Monday as the first day of the week) |
    |       | as a decimal number [00,53]. All days in a new year preceding |
    |       | the first Monday are considered to be in week 0.              |
    ------------------------------------------------------------------------|
    |  %x   | Locale's appropriate date representation.                     |
    ------------------------------------------------------------------------|
    |  %X   | Locale's appropriate time representation.                     |
    ------------------------------------------------------------------------|
    |  %y   | Year without century as a decimal number [00,99].             |
    ------------------------------------------------------------------------|
    |  %Y   | Year with century as a decimal number.                        |
    ------------------------------------------------------------------------|
    |  %Z   | Time zone name (no characters if no time zone exists).        |
    ------------------------------------------------------------------------|
    |  %%   | A literal "%" character.                                      |
    +=======================================================================+

    For more details, see the section on strftime here:

        http://docs.python.org/lib/module-time.html


  LOCALE = 

    This setting defines the locale to use. It is optional as the script will
    determine your systems locale it is not set. However if you tend to setup
    english as the default language in your OS but want all your weather output
    in another langauge you are best setting the locale here.
    
    You also have the option to define locale via command line arguments, if
    these are set then this setting is ignored. This allows for output using a
    variety of languages in multiple script calls for example. 
    
    The locales currently supported are listed against the --locale option in
    the command options help below.


  XOAP_PARTNER_ID = 
  XOAP_LICENCE_KEY = 

    These settings are required for a working script, they are used when
    fetching data from the weather.com XOAP service.
    
    To register and obtain the necessary codes you need to visit the following
    url and fill out the form.

        http://www.weather.com/services/xmloap.html

    After successfully completing the form, you will then receive a couple of
    emails providing you with the necessary codes to update these settings
    with, along with the software development kit and terms and conditions.


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 can combine standard font output with weather fonts in a single 
template by using the execp and execpi commands in conky. The example uses this
so to see how this works take a look at that.

A quick example of template file options and layout:

       [--datatype=DW --startday=1 --shortweekday]

    [--datatype=HT --startday=1 --hideunits]/[--datatype=LT --startday=1 --hideunits]

Anything inside the square brackets are options, anything outside standard text
that will be output as conky would normally handle it.

GOTCHAS
=======

Conky has a default limit of 128 bytes for any text output from a variable.
If you are creating large templates with more characters than the default
buffer size can handle, the output can get truncated.

If this happens you can override the default behaviour by setting as new buffer
size before the TEXT section in your conkyrc file, as follows:

    text_buffer_size 1024

There is a limit to the maximum range for forecasts, the startday and endday
options cannot be set greater than 4. The following are the options to use
to get the maximum forecast of high temps (including forecast data for today)

    --datatype=HT --startday=0 --endday=4

For certain characters used in this script, such as degree symbols, it is
required that the UTF8 character set is enabled in Conky. If UTF8 is not
enabled you can end up seeing something like 66Ã°F rather than 66°F.

To enable UTF8 the following should be added before the TEXT section in your
conkyrc file.

    # Force UTF8? note that UTF8 support required XFT
    override_utf8_locale yes


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 Weather Forecast Python Script
	
    http://ubuntuforums.org/showthread.php?t=869328

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 :)


