14 files changed, 599 insertions, 0 deletions
diff --git a/doc/kworldclock/Makefile.am b/doc/kworldclock/Makefile.am
new file mode 100644
index 0000000..da8216a
--- /dev/null
+++ b/doc/kworldclock/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_LANG = en
+KDE_DOCS = AUTO
+KDE_MANS = AUTO
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:
+
+-->
diff --git a/doc/kworldclock/man-kworldclock.1.docbook b/doc/kworldclock/man-kworldclock.1.docbook
new file mode 100644
index 0000000..a002159
--- /dev/null
+++ b/doc/kworldclock/man-kworldclock.1.docbook
@@ -0,0 +1,92 @@
+<?xml version="1.0" ?>
+<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+<!ENTITY % English "INCLUDE">
+]>
+
+<refentry lang="&language;">
+<refentryinfo>
+  <author><personname><firstname>Ben</firstname><surname>Burton</surname></personname> <email>bab@debian.org</email></author>
+<date>April 8, 2003</date>
+</refentryinfo>
+
+<refmeta>
+<refentrytitle><command>kworldclock</command></refentrytitle>
+<manvolnum>1</manvolnum>
+</refmeta>
+
+<refnamediv>
+<refname><command>kworldclock</command></refname>
+<refpurpose>Earth watcher for &kde;</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>kworldclock</command>
+
+<group><option>--dump</option></group>
+<group><option>--theme</option>
+<replaceable>file</replaceable></group>
+<group><option>-o</option> <replaceable>file</replaceable></group>
+<group><option>--size</option>
+<arg>WxH</arg></group>
+<group><option>KDE Generic Options</option></group>
+<group><option>Qt Generic Options</option></group>
+
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Description</title>
+
+<para>&kworldclock; displays where in the world it is light and dark
+depending on time, as well as offering the time in all of the major
+cities of the world. This can be run standalone, as an applet in the
+&kde; panel, or configured to draw the desktop background.</para> 
+
+<para>&kworldclock; is part of the official &kde; kdetoys
+package.</para>
+
+</refsect1>
+
+<refsect1>
+<title>Options</title>
+
+<variablelist>
+<varlistentry>
+<term><option>--dump</option></term>
+<listitem><para>Write out a file containing the actual
+map</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>--theme</option> <replaceable>file</replaceable></term>
+<listitem><para>The name of the theme to use for a map dump (default:
+earth).</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>-o</option> <replaceable>file</replaceable></term>
+<listitem><para>The name of the file to write to for a map dump
+(default: dump.ppm).</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>--size</option> <replaceable>WxH</replaceable></term>
+<listitem><para>The size of the map to dump.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</refsect1>
+
+<refsect1>
+<title>See Also</title>
+
+<para>More detailed user documentation is available from <ulink
+url="help:/kworldclock">help:/kworldclock</ulink> (either enter this
+<acronym>URL</acronym> into &konqueror;, or run
+<userinput><command>khelpcenter</command>
+<parameter>help:/kworldclock</parameter></userinput>).</para>
+
+</refsect1>
+<refsect1><title>Authors</title><para>&kworldclock; was written by
+&Matthias.Hoelzer-Kluepfel;
+&Matthias.Hoelzer-Kluepfel.mail;</para><para>This manual page was
+prepared by <personname><firstname>Ben</firstname><surname>Burton</surname></personname> <email>bab@debian.org</email></para></refsect1>
+</refentry>
diff --git a/doc/kworldclock/screenshot-clock-dialog.png b/doc/kworldclock/screenshot-clock-dialog.png
new file mode 100644
index 0000000..7477ef6
--- /dev/null
+++ b/doc/kworldclock/screenshot-clock-dialog.png
diff --git a/doc/kworldclock/screenshot-mlb.png b/doc/kworldclock/screenshot-mlb.png
new file mode 100644
index 0000000..8d3c54c
--- /dev/null
+++ b/doc/kworldclock/screenshot-mlb.png
diff --git a/doc/kworldclock/screenshot-quairading-clock.png b/doc/kworldclock/screenshot-quairading-clock.png
new file mode 100644
index 0000000..8ab7d23
--- /dev/null
+++ b/doc/kworldclock/screenshot-quairading-clock.png
diff --git a/doc/kworldclock/screenshot-quairading-dialog.png b/doc/kworldclock/screenshot-quairading-dialog.png
new file mode 100644
index 0000000..17bda5e
--- /dev/null
+++ b/doc/kworldclock/screenshot-quairading-dialog.png
diff --git a/doc/kworldclock/screenshot-rmb-cities.png b/doc/kworldclock/screenshot-rmb-cities.png
new file mode 100644
index 0000000..14c6048
--- /dev/null
+++ b/doc/kworldclock/screenshot-rmb-cities.png
diff --git a/doc/kworldclock/screenshot-rmb-clock.png b/doc/kworldclock/screenshot-rmb-clock.png
new file mode 100644
index 0000000..4f35d24
--- /dev/null
+++ b/doc/kworldclock/screenshot-rmb-clock.png
diff --git a/doc/kworldclock/screenshot-rmb-daylight.png b/doc/kworldclock/screenshot-rmb-daylight.png
new file mode 100644
index 0000000..6371b88
--- /dev/null
+++ b/doc/kworldclock/screenshot-rmb-daylight.png
diff --git a/doc/kworldclock/screenshot-rmb-flags.png b/doc/kworldclock/screenshot-rmb-flags.png
new file mode 100644
index 0000000..17eec15
--- /dev/null
+++ b/doc/kworldclock/screenshot-rmb-flags.png
diff --git a/doc/kworldclock/screenshot-withclocks.png b/doc/kworldclock/screenshot-withclocks.png
new file mode 100644
index 0000000..73f71a1
--- /dev/null
+++ b/doc/kworldclock/screenshot-withclocks.png
diff --git a/doc/kworldclock/screenshot-withflags.png b/doc/kworldclock/screenshot-withflags.png
new file mode 100644
index 0000000..d1efbec
--- /dev/null
+++ b/doc/kworldclock/screenshot-withflags.png
diff --git a/doc/kworldclock/screenshot.png b/doc/kworldclock/screenshot.png
new file mode 100644
index 0000000..3b342ff
--- /dev/null
+++ b/doc/kworldclock/screenshot.png