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


CONTENTS
==========================================================================
* ABOUT
* USAGE
* INFORMATION FOR PACKAGE MAINTAINERS AND DISTRIBUTORS
* MET.NO API DOCUMENTATION
* DEBUGGING AND REPORTING BUGS
* REQUIREMENTS AND DEPENDENCIES
* EASY BUILD INSTRUCTIONS
* TRANSLATING THE PLUGIN FOR YOUR LANGUAGE
* ICON THEMES
* CACHING
* HIDDEN OPTIONS


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. It will also try
to guess and setup your unit system according to the country code.

You can change this location using the Change... button, and searching
for the city, country, address, monument etc. you're interested
in. Only latitude, longitude and altitude (the latter only matters
outside of Norway) will be used for the data requests, so you can edit
the location name to anything you like.

Besides location parameters, the configuration dialog boasts a variety
of other configuration options to alter the appearance of icons,
tooltips and parts of the summary window. On the scrollbox tab you can
choose and rearrange the values presented by the scrollbox.
Middle-click on the font or color button unsets a previously set
font or color.

Tooltips give detailed information about nearly every widget of the
configuration dialog and will tell you what a certain value
(temperature, apparent temperature, wind,...) does and how it can be
interpreted.

On the panel icon, a middle click forces an update, left click brings
up the so-called summary window with a forecast page that shows
forecasts for the next few days and a details page with more
information on the current and plugin data. Right-clicking opens the
contextual menu with more actions.


INFORMATION FOR PACKAGE MAINTAINERS AND DISTRIBUTORS
==========================================================================
If you're going to distribute this package, and legal concerns and
principles allow you to do it, please be so kind and set the
GEONAMES_USERNAME configure option for the GeoNames web service which
is used for altitude and timezone detection. GeoNames requires one to
register an account and limits requests on a per-hour and per-day
basis to prevent misuse of their service. There are no other
restrictions and registration is free, uncomplicated and takes less
than a minute (https://www.geonames.org/export/web-services.html).
Performing these steps will ensure automatic altitude and timezone
detection are kept operational for all users of the plugin. Currently,
it is no big deal and only a precaution, as there are likely not that
many users setting up the plugin within the same hour and exhausting
the credits. Still, if it is ok with you to register a username
yourself for the users of your package, then it would certainly help
should that unlikely case become true. While the user can also set
this via a hidden option, the developer/maintainer of the plugin
thinks the user should not be bothered with it, as every user would
need to do it by default, and that would hurt user experience.


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
  https://api.met.no/weatherapi/documentation
  https://api.met.no/faq.html
  https://api.met.no/license_data.html

* Service-specific documentation
  https://api.met.no/weatherapi/locationforecast/2.0/documentation
  https://api.met.no/weatherapi/sunrise/2.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 open
an issue on https://gitlab.xfce.org/panel-plugins/xfce4-weather-plugin/
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.

First, if you're having trouble with downloading data, then you might
look at the warnings in the panel output. In case of an error, the
HTTP status code will be reported, along with a short text given the
reason, as a result of a download request. It is easy to look up this
code on the web to find more detailed information. Although if it is a
download problem and your connection is ok, then most probably the
service isn't available at the moment due to maintenance or a similar
reason, so just wait some time and try later. Please do not report
bugs about such problems.

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://docs.xfce.org/xfce/xfce4-panel/debugging.

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://gitlab.xfce.org/panel-plugins/xfce4-weather-plugin,
   providing the backtrace.
6) 'quit' exits the debugger.


BUILD REQUIREMENTS AND DEPENDENCIES
==========================================================================
To be able to build the plugin, the following requirements have to be
met in addition to those of XFCE-4.14:

* >=libxml-2.4.0
* >=libsoup-2.42.0
* >=upower-0.9.0 (optional)

You might also need developer libraries necessary for building other
parts of XFCE. Usually autogen.sh / configure will tell you, otherwise
look at the XFCE build instructions https://docs.xfce.org/xfce/building
and the release information https://wiki.xfce.org/releng/4.14/roadmap.


EASY BUILD INSTRUCTIONS
==========================================================================
If you're interesting in building the plugin yourself, these
instructions provided here will work for most users. If not, please
look at the INSTALL file or ask at a forum for your linux distribution
or try the methods explained on https://www.xfce.org/community. Make
sure you have installed the needed dependencies (see previous section
BUILD REQUIREMENTS AND DEPENDENCIES).

For the panel being able to find the plugin, it is important to set
the proper prefix. The prefix is the place in the filesystem where the
plugin files gets installed. It has to match the prefix used for
building the panel. There's nothing the plugin can do about that
requirement. When you're using the panel provided by the package
management system of your distribution, then the prefix is in most
cases /usr, otherwise the default prefix is /usr/local.

If you want to install the current version from git, execute the
following command in the weather plugin project directory (make sure
you have GNU automake installed!):

1a) ./autogen.sh --prefix=/usr

Otherwise, if you've downloaded the tarball from e.g.
https://archive.xfce.org/, issue the following command:

1b) ./configure --prefix=/usr

If 1a) or 1b) fail, you should receive an error message telling you
the cause for the failure (e.g. missings libraries). If you're missing
a dependency you need to install it using the package management
system of your distribution. Distributions commonly have two versions
of a software package: One containing the supplementary files needed
for compiling other packages (usually called "dev"-packages), and the
other one providing the runtime libraries etc. While the latter is
usually installed, the former often is not, so better check this.

Note: To solve distribution-specific problems the most efficient way
is to ask at a forum for your distribution, not on a general forum.

Then for both cases:
2) make

If this fails, file a bug on
https://gitlab.xfce.org/panel-plugins/xfce4-weather-plugin, or
send a mail to the xfce mailing list and provide make output.

Finally, and usually as root:
3) make install

Note: Depending on your prefix, this might overwrite an existing
version of the plugin.

You can later uninstall the plugin (as root) with
4) make uninstall

The panel should then recognize the new plugin, if it doesn't try to
restart it using xfce4-panel -r. If it still doesn't work after that
try to ask for help somewhere (forums, mailing lists, #xfce on
IRC). Please do not report such problems on the bug tracker.


TRANSLATING THE PLUGIN FOR YOUR LANGUAGE
==========================================================================
If you need help getting started with translating the weather plugin
into your language, please visit https://translations.xfce.org/ and
absorb the information that is there, especially on the *Help* page!
There is other useful documentation available on this topic, try this
wiki page for a start:
https://wiki.xfce.org/translations/translation_guidance_in_xfce

TRANSLATORS, PLEASE MAKE SURE YOU CHECK YOUR FILE FOR ERRORS BEFORE
UPLOADING IT! Otherwise, it will break compilation of the plugin. It
is easy to do this with the following command (where file.po is the po
file of your language):
msgfmt -c --check-accelerators=_ -v -o /dev/null <file.po>

This plugin provides a lot of descriptions via the tooltips in the
config dialog. These aim to give short, but interesting explanations
for the various units and available values. While the conventions
should be followed for most of the widgets - you might look up such
agreements and recommendations on the Xfce wiki or ask your
translation team about them -, the descriptions should be translated
in a way that they are understandable and comfortable to read in your
own language, which means that they don't have to be translated
literally. On the contrary, it is recommended that you use your own
words and phrases to get the best results. The author believes this
will make translation much easier and more fun, without denying it can
be quite tedious sometimes.

If your po file is out of date and doesn't contain all strings that
appear in the plugin source code, you can use the build system to
update it for you. See the previous section EASY BUILD INSTRUCTIONS
for setting up the build system and perform step 1a to clone the
repository and generate the make files using automake. If this
succeeds, simply change to the po subdirectory and execute the command
"make update-po". This will regenerate all po files in the po
directory and mark changed strings as fuzzy or obsolete, and add new
strings as untranslated. You can then work on it as usual.

However, if you need to start with a translation completely from
scratch (the po file doesn't exist and isn't listed in transifex),
then please write a mail to xfce@xfce.org or xfce-i18n@xfce.org or use
the bug tracker and ask for such a file being added to the project.
Currently, only the package maintainer or developer of the plugin can
add this new file and include it in the automake files in the git
repository so that it is integrated into the build process and
packaged properly.

Korean translator Seong-ho Cho also recommended the following command
- to be executed in the project's root directory - for creating a
fresh pot file:

xgettext --keyword=_ --keyword=d_:1 --keyword=P_:1,2 --keyword=P_:1,2 --keyword=N_ --keyword=NP_:1,2 --from-code=UTF-8 --foreign-user --output=xfce4-weather-plugin.master.untitled.pot panel-plugin/*.[ch]

This gives a po-template file with untranslated strings, with the
advantage being that this only requires the gettext package to be
installed. Of course, you can always simply ask the developer/package
maintainer to generate and add a new po file for your language, so
that you can download it using transifex.


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

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

As of 0.8.3, xfce4-weather-plugin supports icon themes. This requires
a specific icon naming scheme that corresponds to the met.no API
symbols definition. Icon sets following the freedesktop.org
standardized naming scheme are not supported because they lack too
many icons the plugin would need for the various weather conditions
provided by met.no, so adhereing to the standard wouldn't make much
sense (see the next section 2) for more information).

If you want to design your own set, please have a look at the default
Liquid theme that is included in this package 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.

The plugin searches for icon themes in the following directories, in
this particular order (this very same order will be used for listing
the themes in the configuration dialog):
$XDG_CONFIG_HOME/xfce/weather/icons
$(datadir)/icons

Where
* $XDG_CONFIG_HOME is usually /home/user/.config
* $(datadir) is whatever you configured it to be on build-time, like
  /usr/local/share/xfce4/weather/icons or
  /usr/share/xfce4/weather/icons

In these directories the plugin shall find subdirectories that contain
the icon themes. Let's look at the structure by example of the Liquid
theme (files or directories in brackets [] are optional):

Liquid
|--22
|--48
|--128
\--theme.info

The theme.info file needs to be present, or the plugin will not
consider the directory a valid icon theme. This file may contain
the following entries:
------------------------------- theme.info -------------------------------
Name=Liquid
Author=Unknown
Description=Modified icon theme originating from the Superkaramaba Liquid Weather plugin
License=GPL-2
-------------------------- theme.info ends here --------------------------

Make sure that each entry is on one line. Entries may not span
multiple lines, all additional lines will be ignored. You can use \n
for newlines, though. These values will be shown in the tooltip of the
theme selection combo box in the configuration dialog. You might want
to put an extra LICENSE file into your theme directory.

Directories 22, 48 and 128 shall contain the icons in PNG format (or
at least with a PNG extension) at approximately the size the directory
names suggest. Icon sizes for the panel icon will be chosen depending
on the panel size. For the tooltip, the icon will be taken from the
128 directory, and medium sized icons (48) for the forecast window and
similar places.

Here is a list showing which icon sizes are recommended for the
various panel sizes:

Directory   Panel size    Recommended icon sizes
22          16-23         22, 24, 16
48          24-48         48, 24, 32
128         49-128        128, 96, 80, 64

To be found by the plugin, the icons need to be named exactly as
follows (listed in alphabetical order):

* cloud.png
* fog.png
* lightcloud.png
* lightrain.png
* lightrainsun.png
* lightrainthunder.png
* lightrainthundersun.png
* nodata.png
* partlycloud.png
* rain.png
* rainthunder.png
* sleet.png
* sleetsun.png
* sleetsunthunder.png
* sleetthunder.png
* snow.png
* snowsun.png
* snowsunthunder.png
* snowthunder.png
* sun.png

At night time, the plugin will first look for icons having a "-night"
suffix, e.g. partlycloud-night.png, lightrainsun-night.png etc. The
rest of the filename needs to be the same as for the day icon, and the
icons should probably look similar, however with brother sun replaced
by sister moon. Of course, the latter is rather a design decision than
a technical necessity. If no night variant is provided, the plugin
will fallback to using the day icon.

Note that not all symbols are expected to have icons for night
time. For example, the CLOUD symbol is used when there is 100%
cloudiness and the sun or moon cannot be seen. However, the plugin
will still look for such night icons, in case the designer has another
idea how to indicate night time without creating confusion.

The only exception to this is the icon for NODATA, which has no night variant.
This icon will only be shown when the plugin has not been configured yet -
but then more likely only the NODATA icon of the default theme will
appear and not that of your theme -, or when there is no data
available, for example in case of a network error. It also serves as
the fallback icon for all missing day icons. Finally, if you do not
provide a NODATA icon for your theme, then the one of the default
theme will be used which is assumed to always be present.

If the plugin can't find a specific icon, it will remember that it is
missing and not try to read it again until you restart the panel for
change the theme. Also, icons for the panel and for the tooltip will
be cached. These are measures to minimize disk access. Just keep that
in mind when you work on your icons when the plugin is running.

All icon sets included and distributed in the xfce4-weather-plugin
package are under GPL by default.

2) Freedesktop standardized naming scheme
--------------------------------------------------------------------------

It was suggested (https://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
https://specifications.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!

3) The "Liquid" icon theme and its license
--------------------------------------------------------------------------

In August 2012 a question was raised about the license of the Liquid
icon theme (see https://mail.xfce.org/pipermail/xfce/2012-August/031178.html
and https://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
https://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.


CACHING
==========================================================================
As of 0.8.3, xfce4-weather-plugin caches downloaded weather and
astronomical data. Per plugin instance, one file containing that
cached data is created in the user cache directory, typically in
$HOME/.cache/xfce4/weather. This file will be generated or overwritten
on every weather data download and read before any location data
change. Cached data has a certain expiry date and will not be used if
it is older than that. There is an option not exposed by the UI to
change the maximum age; This parameter is called "cache_file_max_age"
and can be found in the plugin configuration file usually located in
~/.config/xfce4/panel. It is set to the maximum age in seconds and
defaults to 48 hours (172800 seconds).

By using caching, some deficiencies of data provided by met.no can be
worked around:

First, their location forecast service wasn't really meant to provide
data for the current weather, which the plugin tries to convey.
However, the forecasts for the next few hours (typically the next 3
hours or sometimes even the next hour for cities, in any case at max 6
hours for all locations) are in most cases good enough to fake current
conditions using interpolation. Note that other weather providers
often present values for current weather that have been measured half
an hour or even more ago, so in most cases it won't make a big
difference.

Second, caching reduces network traffic. Data will only be downloaded
after the download interval time has expired. Information about
download times can be seen in the details page of the summary window.

Third, caching data enables the plugin to work without internet
connection for some time (see the previous paragraph about
cache_file_max_age for information about configuring this expiry
time).

Note that refreshing data by middle-clicking the icon or by clicking
on the appropriate context menu entry does not clear the cache.
However, data that has been downloaded will always overwrite any
existing data.


HIDDEN OPTIONS
==========================================================================
Further options are available which are not exposed via the UI because
they are usually not needed. To add or edit these, quit the panel with
"xfce4-panel -q", make the desired modifications to the appropriate
config file in $HOME/.config/xfce4/panel, then restart the panel with
"xfce4-panel &".

* cache_file_max_age: Maximum allowed age of the cache file in seconds.
  See the previous section CACHING for an explanation.

* geonames_username: The GeoNames webservices are credit-based, and
  although the plugin uses them only for setting up its configuration,
  the credits could get exhausted if many users use the plugin. This
  configuration option gives the user the chance to set a registered
  GeoNames username manually (see INFORMATION FOR PACKAGE MAINTAINERS
  AND DISTRIBUTORS on how to register). Delete this option completely
  to use the default GeoNames username set at build time.

* power_saving: If the plugin has been compiled with support for
  upower, it will try to extend battery life by taking the following
  measures:
  If the machine is on battery,
     - decrease the regular update interval to 30 seconds,
     - stop the scrollbox animation and
     - update the summary window clock only every minute.
  Setting this value to false will deactivate power saving. If upower
  support has not been compiled in, then this setting will have no
  effect.