Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdetoys@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 260 insertions, 0 deletions

diff --git a/doc/kweather/index.docbook b/doc/kweather/index.docbook
new file mode 100644
index 0000000..e545a5a
--- /dev/null
+++ b/doc/kweather/index.docbook
@@ -0,0 +1,260 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kweather  "<application>kweather</application>">
+  <!ENTITY package "kdetoys">
+  <!ENTITY % English "INCLUDE">
+  <!ENTITY % addindex "IGNORE">
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The KWeather Handbook</title>
+
+<authorgroup>
+<author>
+<firstname></firstname>
+<othername></othername>
+<surname></surname>
+<affiliation>
+<address><email></email></address>
+</affiliation>
+</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<legalnotice>&GPLNotice;</legalnotice>
+
+<date>2004-05-31</date>
+<releaseinfo>3.00.00</releaseinfo>
+
+<abstract>
+<para>
+KWeather is part of the kdetoys package.
+</para>
+</abstract>
+
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>KWeather</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>KWeather is an application that provides both a panel icon,
+allowing you to watch the weather as reported by a local weather
+station,  and providing a weather service that can track multiple
+weather  stations and provide this information to other
+applications including &konqueror;'s sidebar and &kontact;'s
+summary page.</para>
+
+</chapter>
+
+<chapter id="adding-applet">
+<title>Using KWeather as a Panel Applet</title>
+
+<para>&RMB; click on an empty space in the panel and choose
+<menuchoice><guimenu>Add</guimenu><guisubmenu>Applet</guisubmenu>
+<guimenuitem>KWeather</guimenuitem></menuchoice></para>
+
+<para>A configuration dialog will open up.  Initially the only
+configuration required to make KWeather work is the <guilabel>ICAO
+location code:</guilabel>.</para>
+
+<para>This is a four character code used by the weather reporting
+service to uniquely identify weather stations around the world.</para>
+
+<para>As it's unlikely that most people will happen to know this
+directly, there is a link to a search engine where you can look it
+up.</para>
+
+<note><para>While the weather stations available are fairly
+comprehensive, not every town in every country will be represented,
+simply because not every town has an appropriate weather station.  If
+your own town is not represented, you should choose the one nearest
+you.  Since flying planes safely requires accurate weather data, most
+towns with an airport will be in the list, so a good bet
+is to look for the nearest airport to you.</para></note>
+
+<para>At this point, you can press the <guibutton>OK</guibutton> button
+and the dialog will close.  You will now have an icon displaying the
+current weather graphically on your panel.  Clicking it once will open
+a window that shows the weather in detail.</para>
+
+<para>Further configuration is described in the next chapter.</para>
+
+</chapter>
+
+<chapter id="configuring-kweather">
+<title>Configuring KWeather</title>
+
+<sect1 id="display">
+<title>Display</title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Weather Station Options</guilabel></term>
+<listitem>
+  <variablelist>
+  <varlistentry>
+  <term><guilabel>ICAO location code:</guilabel></term>
+  <listitem><para>ICAO stands for the International Civil Aviation
+Organization.  The ICAO location code is a four character
+alphanumeric code that uniquely identifies airports worldwide.  The first
+two letters of the ICAO code ususally identify the coutry.  However, codes for 
+airports in the United States usually start with "K", followed by a three 
+character IATA (International Air Transport Assocation) code.  For example,
+KORD is the ICAO code for Ohare International Airport in Chicago, Illinois.  
+If you don't know the ICAO code for the airport nearest to you, you can click
+on the link labeled <guilabel>Lookup Your ICAO Code</guilabel> to use a web based
+search engine to find it.</para></listitem>
+  </varlistentry>
+  </variablelist>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Panel Display Options</guilabel></term>
+<listitem>
+  <variablelist>
+  <varlistentry>
+  <term><guilabel>Show icon only</guilabel></term>
+  <term><guilabel>Show icon and temperature</guilabel></term>
+  <term><guilabel>Show icon, temperature, wind and pressure information</guilabel></term>
+  <listitem><para>You can choose here if the temperature should be
+displayed beside the icon, or if the current wind speed, direction, and
+air pressure are also displayed.</para>
+  <para>The icon is always shown.</para>
+  </listitem>
+  </varlistentry>
+  </variablelist>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Logging Options</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Enable logging</guilabel></term>
+<listitem><para>By default KWeather does not retain old weather
+information, and each time it updates the weather the old information
+is discarded.  If you wish instead to keep a record of the weather,
+enable this option.  Then, each time the weather is checked, KWeather
+will append a new line to the log file containing the current weather
+conditions in comma separated value form.  The information written 
+will be the date, wind speed and direction, temperature, pressure, cover,
+visibility, and "current weather".</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Log file</guilabel></term>
+<listitem><para>If you have enabled the <guilabel>Enable
+logging</guilabel> check box, this option will become available.  Enter
+or  browse to the location you would like KWeather to keep it's log
+file.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="weather-service">
+<title><guilabel>Weather Service</guilabel></title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Station Manager</guilabel></term>
+<listitem><para></para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Update All Stations</guibutton></term>
+<listitem><para>Update all the listed stations
+immediately.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Exit Weather Service</guibutton></term>
+<listitem><para>Stop fetching weather updates for all
+listed stations, and stop providing weather
+information to the &konqueror; sidebar and &kontact;</para></listitem>
+</varlistentry> </variablelist> </sect1>
+
+</chapter>
+
+<chapter id="kweather-interfaces">
+<title>KWeather Interfaces</title>
+
+<para>While the most obvious KWeather interface is the panel icon,
+there are several other places where you can access KWeather's
+information.  These are particularly useful if you need to watch
+multiple weather stations. While &kweather; allows you to track
+multiple weather stations, the panel icon displays only one at a
+time.</para>
+
+<para>These additional services are plug-ins to their respective
+applications, and not provided with KWeather itself.</para>
+
+<!-- FIXME: write some stuff and show some screenies of the konq and
+kontact plugins -->
+
+</chapter>
+
+<chapter id="credits-and-licenses">
+<title>Credits and Licenses</title>
+
+<para>KWeather copyright &copy; Ian Reinhart Geiser
+<email>[email protected]</email></para>
+
+<variablelist>
+<title>Contributors</title>
+<varlistentry><term>Will Andrews
+<email>[email protected]</email></term>
+<listitem><para>Fixes for BSD port</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Ben Burton <email>[email protected]</email></term>
+<listitem><para>Debian fixes</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Otto Bruggeman <email>[email protected]</email></term>
+<listitem><para>Fixed the i18n stuff and source style
+cleanups</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Nadeem Hasan <email>[email protected]</email></term>
+<listitem><para>Lots of bug fixes, improvements and
+cleanups.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Carles Carbonell Bernado <email>[email protected]</email></term>
+<listitem><para>Great new weather icons</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>John Ratke <email>[email protected]</email></term>
+<listitem><para>Improvements and more code cleanups</para></listitem>
+</varlistentry>
+</variablelist>
+
+&underGPL;
+&underFDL;
+
+</chapter>
+
+&documentation.index;
+</book>
+
+<!--
+Local Variables:
+mode: sgml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+// vim:ts=2:sw=2:tw=78:noet
+-->