XFCE4-WEATHER-PLUGIN
==========================================================================
You can always find up-to-date information at the plugin homepage:
http://goodies.xfce.org/projects/panel-plugins/xfce4-weather-plugin


ABOUT
==========================================================================
Originally written by Bob Schlärmann, this panel plugin shows
information about your local weather in the panel, using forecast data
provided by met.no.


USAGE
==========================================================================
The first time you open the configuration dialog, the weather plugin
automatically configures itself to fetch weather data from a place
which should be near you - based on your IP address.

You can change this location using the Change... button, and searching
for the city, country, address, monument etc. you're interested
in. Only latitude and longitude will be used for the data requests, so
you can edit the location name to something you like.

In this configuration screen, you can also choose which information
you want visible in the panel.

On the panel icon, a middle click forces an update, left click brings
up a forecast and details page. Right-clicking opens the contextual
menu.


MET.NO API DOCUMENTATION
==========================================================================
To get a quick overview, please consolidate the met.no API weather
documentation and especially their FAQ, which answers some questions
left open by the former:

* General documentation and data licensing
  http://api.yr.no/weatherapi/documentation
  http://api.yr.no/faq.html
  http://api.met.no/license_data.html

* Service-specific documentation
  http://api.met.no/weatherapi/locationforecastlts/1.1/documentation
  http://api.yr.no/weatherapi/sunrise/1.0/documentation

For more technical details you might need to study the XML schema
corresponding to the document in question.


DEBUGGING AND REPORTING BUGS
==========================================================================
Before reporting bugs or asking for new features, please consolidate
the Xfce bug tracker at https://bugzilla.xfce.org and check the TODO
file, because your issue or request might have been reported already
or be in planning. However, feel free to add any information not yet
mentioned that you find useful.

If you encounter problems like crashes or weird behaviour, it might
prove insightful to enable panel debugging as follows:

1) Quit the current running panel instance using 'xfce4-panel -q'.
2) Set the PANEL_DEBUG environment variable to 'weather' or 'all':
   export PANEL_DEBUG=weather
3) Start the panel and let it write its output to a file, e.g.:
   xfce4-panel > panel.log 2>&1 & disown
4) Watch output using tail -f or less or whatever you like:
   tail -f panel.log

This will make the plugin explain what it's currently doing and dump
data it downloaded from the various sources. More information about
debugging panel plugins can be obtained from several pages of the Xfce
Wiki at https://wiki.xfce.org.

It's also relatively easy and often very helpful to create a backtrace
using gdb or any other debugger should the plugin crash:

1) Find the process ID of the weather plugin with something like
   'pgrep -f libweather.so'. Let's assume the resulting PID is 1234.
2) Attach the GNU debugger to that process: 'gdb attach 1234'.
3) The plugin will be frozen now. Tell the debugger to let it continue
   with the 'cont' command.
4) Produce the crash if possible, or wait until it crashes.
5) GDB will detect the crash and freeze the plugin again. Use 'bt' to
   print a nice backtrace. Report the issue to the Xfce bugtracker at
   https://bugzilla.xfce.org, providing the backtrace.
6) 'quit' exits the debugger.


ICON THEMES
==========================================================================

1) Icon theme support
--------------------------------------------------------------------------

Currently, there is no real icon theme support, but this will be
worked on in one of the next releases. Until that feature is
implemented, you can of course replace the liquid weather icons with
your own, however this will in most cases require root permissions. If
you want to design your own set, please have a look at the liquid
theme to get an idea what the icons should look like and at the source
file weather-translate.c, where you will find references and
explanations for the weather symbols.

It was suggested (http://mail.xfce.org/pipermail/xfce/2012-August/031180.html)
to make use of icon themes implementing the freedesktop standardized naming
scheme, like some KDE and GNOME application do, for reference please see
http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html.

This might not be such a good idea, however, because
* the standard only provides a limited set of weather icons which will
  not be enough to represent all possible conditions the weather plugin
  can show,
* it is unclear what to do when those icons are missing, and solving
  this in a good manner will make things unnecessarily complicated for
  the plugin,
* with the liquid icon set there already is a good default icon set that
  suits most users,
* the deficiences of the liquid theme can be solved more easily with
  proper theming support and a bit of editing (providing an
  alternative liquid theme for dark panels).

Of course, you might take any such freedesktop compliant theme as the
basis for your personal new icon set, so you only have to design or
assemble the remaining few icons. And finally, with a bit of searching
you can find lots of free-to-use icons and icon sets on the web!

2) The "liquid" icon theme and its license
--------------------------------------------------------------------------

In August 2012 a question was raised about the license of the liquid
icon theme (see http://mail.xfce.org/pipermail/xfce/2012-August/031178.html
and http://mail.xfce.org/pipermail/xfce/2012-August/031188.html for
further discussion), so let's elaborate a bit on that.

According to original author of the plugin, Bob Schlärmann, the
"liquid" icon theme originates from the now abandoned "Liquid Weather"
package for KDE Superkaramba and has been part of the weather plugin
since around 2004. While this is not 100% certain, it is supposed to
be licensed under GPL-2, as is the "Liquid Weather" script.

Unfortunately, the Liquid Weather website at liquidweather.net is no
more, and so obtaining the script package is a bit difficult and
requires searching for mirrors. A link that still works at the time of
this writing is:
ftp://ftp.wanadoo.nl/pub/mirrors/FreeBSD/ports/distfiles/lwp-15.0.skz

However, trying to contact the developers of Liquid Weather in
September 2012 for verification about this issue did not yield any
response.

An archived version of the website which contains information about
the previously available icon sets and the license is still available at
http://web.archive.org/web/20100724155753/http://liquidweather.net/icons.php:
"On this page, you'll find additional iconsets and backgrounds for
liquid weather ++ - please note that the backgrounds are not easily
installable with versions earlier than v9.0. With the exception of the
weather.com, Beginning and Um icons, I believe that these iconsets are
either GPL or available for redistribution. If I am wrong, please let
me know and I'll remove them. Please note that the weather.com icons
are used with permission of the weather.com website, and the Beginning
and Grzanka icons are used with the permission of their authors. This
means that these iconsets may not be copied, modified or redistributed
without permission. The same applies to the Umicons included in the
core liquid weather tarball."

A further look at http://kde-look.org/content/show.php?content=6384,
brings forth this bit of information: "License: Everything is GPL,
EXCEPT FOR some of the icon sets, which are distributed with the
permission of their authors." Looking at the archived web page above,
the liquid weather icon set is not to be found in the exceptions list,
so according to that it should be GPL. Besides, the similarity of the name of both
the icon set and its containing package also hints to that licensing.

To sum it all up, the icon theme is considered licensed under GPL too,
though its original author remains unknown. If someone can resolve this,
please send a mail to the current maintainer of the weather plugin, and
he/she will give proper credit.
