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, 503 insertions, 0 deletions

diff --git a/doc/kworldclock/index.docbook b/doc/kworldclock/index.docbook
new file mode 100644
index 0000000..33b5e8a
--- /dev/null
+++ b/doc/kworldclock/index.docbook
@@ -0,0 +1,503 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kappname "&kworldclock;">
+  <!ENTITY package "kdetoys">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE">    
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The &kworldclock; Handbook</title>
+
+<authorgroup>
+<author>
+&Brad.Hards;
+&Brad.Hards.mail;
+</author>
+</authorgroup>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+
+<copyright>
+<year>2004</year>
+<holder>Brad Hards</holder>
+</copyright>
+<legalnotice>&FDLNotice;</legalnotice>
+
+
+<date>2004-01-22</date>
+<releaseinfo>0.00.00</releaseinfo>
+
+<abstract>
+<para>
+&kworldclock; is an application that shows which parts of the world
+are currently experiencing daylight, and which parts are currently in
+night. It also shows the current time in a range of cities around the
+world.
+</para>
+</abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>kdetoys</keyword>
+<keyword>kworldwatch</keyword>
+<keyword>World Clock</keyword>
+<keyword>day / night clock</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+
+<para>
+&kworldclock; is an application that shows which parts of the world
+are currently experiencing daylight, and which parts are currently in
+night. It also shows the current time in a range of cities around the
+world.
+</para>
+
+<para>
+Please report any problems or feature requests to the &kde; mailing lists.
+</para>
+</chapter>
+
+<chapter id="using-kapp">
+<title>Using &kworldclock;</title>
+
+<sect1><title>The main display</title>
+<para>
+When you start &kworldclock;, you will see a small window appear, as
+shown below.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>Here's a screenshot of &kworldclock;</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="screenshot.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Screenshot</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+The light section (which in the screenshot above covers Antartica,
+Australia, eastern and southern Africa and most of Asia; plus the
+Indian Ocean and the western part of the Pacific Ocean) shows the area
+that is currently experiencing daylight, while the darker section
+(which in the screenshot above covers western Europe, North and South
+America, and the Arctic zone) shows the area that is currently
+experiencing night. The border between the dark and light section
+is the area that is experiencing morning or evening twilight.
+</para>
+
+<para>
+Each small black square indicates a city or population centre.  If you
+locate the mouse over (or near) one of the black squares, you will see
+the date and time that is current for that location.  In the
+screenshot above, the tiny island of Pitcairn is shown.
+</para>
+
+<para>
+You may find it more convenient to expand the window, so that there is
+more space between the various squares. Remember that you can expand the window by
+either clicking on the maximise button (second button from the right in the
+top right hand corner) or by using the mouse to drag the corner of the
+main window. An expanded window, with Melbourne (Australia) now
+selected, is shown below.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>Screenshot of &kworldclock; with expanded window</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="screenshot-mlb.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Screenshot showing expanded window, with Melbourne
+selected.</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+</sect1>
+
+<sect1 id="kworldclock-clocks"><title>Configuring &kworldclock; with timezone clocks</title>
+
+<para>
+If you need to know the time in a number of areas around the world, it
+may be useful to have &kworldclock; show the applicable times. An
+example of how this can look is shown below.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>Screenshot of &kworldclock; with clocks</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="screenshot-withclocks.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Screenshot showing expanded window, with three clocks.</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+Note the clocks for Perth, Sydney and Berlin at the bottom of the main
+&kworldclock; window. 
+</para>
+
+<para>
+These clocks are added by using the right mouse button, and selecting
+the <guilabel>Clock</guilabel> entry, as shown below.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>Screenshot of &kworldclock; &RMB; clock</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="screenshot-rmb-clock.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Screenshot showing &RMB; menu, with
+<guilabel>Clock</guilabel> selected.</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+This will allow access to the <guilabel>Add...</guilabel> selection,
+which will bring up a dialog box as shown below. The contents of the
+dialog box are determined from the closest city to the mouse cursor
+when you make the selection.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>Screenshot of &kworldclock; <guilabel>Edit Clock
+Settings</guilabel> dialog</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="screenshot-clock-dialog.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Screenshot showing<guilabel>Edit Clock
+Settings</guilabel> dialog.</phrase> 
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+
+<para>
+You can now make an appropriate selection for the clock label and the
+timezone. Note that you can change the label to whatever is
+appropriate, and the timezone as required. An example, for the small
+Australian town of Quairading, is shown below.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>Screenshot of &kworldclock; <guilabel>Edit Clock
+Settings</guilabel> dialog changed to Quairading</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="screenshot-quairading-dialog.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Screenshot showing <guilabel>Edit Clock
+Settings</guilabel> dialog for Quairading.</phrase> 
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+When you select OK, the clock entry is added to those at the bottom of
+the main window. A screenshot, with the extra entry for Quairading, is
+shown below.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>Screenshot of &kworldclock; with Quairading clock</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="screenshot-quairading-clock.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Screenshot showing Quairading clock.</phrase> 
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+You might notice that Perth and Quairading are now showing the same
+information (since they are in the same timezone). In this case, the
+Perth entry is no longer required, so it can be removed. This can be
+done by again using the right mouse button on the clock display, and selecting
+the <guilabel>Remove</guilabel> item.
+</para>
+
+<para>
+You can also edit entries by using the <guilabel>Edit...</guilabel>
+entry on right mouse button menu, which may be useful for making
+minor changes.
+</para>
+
+</sect1>
+
+<sect1 id="kworldclock-flags"><title>Adding Flags to the &kworldclock; display</title>
+
+<para>
+As shown in the screenshot below, you can add flags to places on the
+map (in this case, Fremantle near Perth, Western Australia; near
+Moscow in Russia; and the Azores in the mid-Atlantic). These flags
+don't affect any other functionality - they just allows you to quickly
+locate places of interest.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>Screenshot of &kworldclock; with flags</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="screenshot-withflags.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Screenshot showing expanded window, with three flags.</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+You add flags by locating the mouse at the point where you want to
+appear, and using the right mouse button to select the the
+<guilabel>Flags...</guilabel> entry. You can select one of the three
+pre-defined flag colours (that is, <guilabel>Add Red</guilabel>,
+<guilabel>Add Green</guilabel> or <guilabel>Add Blue</guilabel>), or
+you can select a custom colour.
+</para>
+
+<para>
+You use the same menu action to remove just one flag (whichever one is
+closest to the mouse when you make the <guilabel>Remove
+Flag</guilabel> selection; or to remove all the flags, using the
+<guilabel>Remove All Flags</guilabel>.
+</para>
+
+</sect1>
+
+<sect1 id="kworldclock-display"><title>Changing the &kworldclock; display</title>
+
+<para>
+In addition to the additional clocks and flags, there are other minor
+variations you can make to the main &kworldclock; display, such as not
+showing the flags, not showing the small black city squares, and not
+showing the day/night areas. Each of these is selected using the right
+mouse button menu.
+</para>
+
+<para>
+To enable and disable the display of the day / night sections, you use
+the right mouse button, and select the <guilabel>Show
+Daylight</guilabel> item from the menu. Each time you select it, the
+selection will be toggled. When showing day and night is enabled
+(normal mode on first startup), there will be a small check mark
+(tick symbol) next to the <guilabel>Show Daylight</guilabel>. An
+example of the menu item (with day / night not enabled, hence no check
+mark) is shown below.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>Screenshot of &kworldclock; &RMB; daylight</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="screenshot-rmb-daylight.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Screenshot showing &RMB; menu, with
+<guilabel>Show Daylight</guilabel> selected.</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+
+<para>
+To enable and disable the display of the small black city squares, you use
+the right mouse button, and select the <guilabel>Show
+Cities</guilabel> item from the menu. Each time you select it, the
+selection will be toggled. When showing cities is enabled
+(normal mode on first startup), there will be a small check mark
+(tick symbol) next to the <guilabel>Show Cities</guilabel>. An
+example of the menu item (with city display enabled, hence a check
+mark) is shown below.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>Screenshot of &kworldclock; &RMB; show cities</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="screenshot-rmb-cities.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Screenshot showing &RMB; menu, with
+<guilabel>Show Cities</guilabel> selected.</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+To enable and disable the display of the flags, you use
+the right mouse button, and select the <guilabel>Show
+Flags</guilabel> item from the menu. Each time you select it, the
+selection will be toggled. When showing flags is enabled
+(normal mode on first startup), there will be a small check mark
+(tick symbol) next to the <guilabel>Show Flags</guilabel>. An
+example of the menu item (with flags enabled, hence a check
+mark) is shown below.
+</para>
+
+<para>
+<screenshot>
+<screeninfo>Screenshot of &kworldclock; &RMB; show flags</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="screenshot-rmb-flags.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Screenshot showing &RMB; menu, with
+<guilabel>Show Flags</guilabel> selected.</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+<para>
+After reconfiguring &kworldclock;, you may wish to save your
+settings. This is done using the right mouse button, and selecting the
+<guilabel>Save Settings</guilabel> option.
+</para>
+
+</sect1>
+
+<sect1 id="kworldclock-maps"><title>Selecting alternative maps</title>
+<para>
+In addition to the normal surface depth map, you can add additional
+maps, which can be selected using the <guilabel>Map Theme</guilabel>
+item from the right mouse button menu. &kworldclock; comes with a
+single map, which provides surface depth (relief). Additional maps can be obtained from 
+<ulink url="http://www.radcyberzine.com/xglobe">http://www.radcyberzine.com/xglobe</ulink>.
+Maps need to be appropriately installed - typically into
+<filename>share/apps/kworldclock/maps</filename> under the main &kde;
+directory. Consult your system administrator for assistance in doing
+this, if required.
+</para>
+
+<para>
+If you want to use your own map, you should make sure
+that Greenwich is exactly in the middle of the map, and provide an
+appropriate desktop file.
+</para>
+
+</sect1>
+
+</chapter>
+
+<chapter id="developers">
+<title>Developer's Guide to &kworldclock;</title>
+
+<para>
+The most common requirement for development of &kworldclock; is to add
+additional cities to the map. The cities are determined by a file
+named <filename>zone.tab</filename>, which is located under
+<filename>share/apps/kworldclock</filename> under the main &kde;
+directory.
+</para>
+
+<para>
+To add an additional city, you need to know the latitude and
+longitude, and also the applicable time zone information. There is
+additional information on the exact format required in the
+<filename>zone.tab</filename> file.
+</para>
+
+</chapter>
+
+<chapter id="credits">
+<title>Credits and License</title>
+
+<para>
+&kworldclock;
+</para>
+<para>
+Program copyright 2000 Matthias Hoelzer-Kluepfel.
+</para>
+
+<para>
+Documentation Copyright &copy; 2004 &Brad.Hards; &Brad.Hards.mail;.
+</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;               <!-- FDL: do not remove -->
+
+
+&underGPL;        	 <!-- GPL License -->
+</chapter>
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="getting-kapp">
+<title>How to obtain &kworldclock;</title>
+
+
+
+&install.intro.documentation;
+
+</sect1>
+
+<sect1 id="compilation">
+<title>Compilation and Installation</title>
+
+
+&install.compile.documentation;
+
+</sect1>
+
+</appendix>
+
+&documentation.index;
+</book>
+
+<!--
+Local Variables:
+mode: xml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+-->