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/kdenetwork@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

21 files changed, 1407 insertions, 0 deletions

diff --git a/doc/knewsticker/Makefile.am b/doc/knewsticker/Makefile.am
new file mode 100644
index 00000000..085981d9
--- /dev/null
+++ b/doc/knewsticker/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_LANG = en
+KDE_DOCS = AUTO
+
diff --git a/doc/knewsticker/TODO b/doc/knewsticker/TODO
new file mode 100644
index 00000000..72208730
--- /dev/null
+++ b/doc/knewsticker/TODO
@@ -0,0 +1,4 @@
+TODO
+----
+* Make the developer's chapter use the <refentry> stuff if somebody finds out
+  how it works :-]
diff --git a/doc/knewsticker/about-icon.png b/doc/knewsticker/about-icon.png
new file mode 100644
index 00000000..d2866407
--- /dev/null
+++ b/doc/knewsticker/about-icon.png
diff --git a/doc/knewsticker/checknews-icon.png b/doc/knewsticker/checknews-icon.png
new file mode 100644
index 00000000..ce2468a8
--- /dev/null
+++ b/doc/knewsticker/checknews-icon.png
diff --git a/doc/knewsticker/contextmenu.png b/doc/knewsticker/contextmenu.png
new file mode 100644
index 00000000..c3b313a0
--- /dev/null
+++ b/doc/knewsticker/contextmenu.png
diff --git a/doc/knewsticker/help-icon.png b/doc/knewsticker/help-icon.png
new file mode 100644
index 00000000..d21faa26
--- /dev/null
+++ b/doc/knewsticker/help-icon.png
diff --git a/doc/knewsticker/index.docbook b/doc/knewsticker/index.docbook
new file mode 100644
index 00000000..1532f8b1
--- /dev/null
+++ b/doc/knewsticker/index.docbook
@@ -0,0 +1,1399 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+<!ENTITY kappname "&knewsticker;">
+<!ENTITY package "kdenetwork">
+<!ENTITY % addindex "IGNORE">
+<!ENTITY % English "INCLUDE">
+<!ENTITY RSS "<acronym>RSS</acronym>">
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The &knewsticker; Handbook</title>
+
+<authorgroup>
+	<author>&Frerich.Raabe; &Frerich.Raabe.mail;</author>
+	<othercredit role="reviewer">&Jonathan.Singer; &Jonathan.Singer.mail;</othercredit>
+	<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<copyright>
+	<year>2001, 2002, 2003</year>
+	<holder>&Frerich.Raabe;</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2003-10-14</date>
+<releaseinfo>2.00.00</releaseinfo>
+
+<abstract>
+	<para>&knewsticker; is a news ticker applet for the &kde; panel (also
+	known as &kicker;).</para>
+</abstract>
+
+<keywordset>
+	<keyword>KDE</keyword>
+	<keyword>KNewsTicker</keyword>
+	<keyword>kdenetwork</keyword>
+	<keyword>news ticker</keyword>
+	<keyword>applet</keyword>
+</keywordset>
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>&knewsticker; is an applet for the &kde; panel (also known as &kicker;)
+which provides an easy and convenient way to access the news as reported by
+many news sites (such as <ulink url="http://slashdot.org">Slashdot</ulink>,
+<ulink url="http://lwn.net">&Linux; Weekly News</ulink> or
+<ulink url="http://freshmeat.net">Freshmeat</ulink>).</para>
+
+<para>To achieve this, &knewsticker; requires the news sites to provide a
+special &RSS; file, which contains the headlines as well as
+pointers to the corresponding full articles. Such files are very common these
+days, and &knewsticker; already comes with a selection of good news sources
+which provide such files.</para>
+
+<sect1 id="rssfiles">
+<title>Brief Info On &RSS; Files</title>
+
+<para>&RSS; files are becoming more and more popular these
+days, and this applet is not the first application which takes advantage of
+them. But what are &RSS; files? This section tries to give
+a brief answer to this question, as well as pointers to other sources for
+further reference.</para>
+
+<para>The short answer: &RSS; is an
+<acronym>&XML;-based</acronym> format for syndicating web content.</para>
+
+<para>&RSS; is often used as an acronym for <quote>Rich Site
+Summary</quote> &ndash; that's not a common definition but it gives an idea on what
+the creators of &RSS; had in mind. There is no consensus on
+what &RSS; stands for, so it's actually not an acronym, it's a
+name.</para>
+
+<para>&RSS; originated in 1999 and was invented by
+<ulink url="http://www.netscape.com">NetScape</ulink> as a syndication format
+for their <ulink url="http://my.netscape.com">my.netscape.com</ulink> website;
+this very first &RSS; release was version 0.9. A few months
+after that, &Netscape; introduced &RSS; version 0.91, which
+incorporated many features of the <quote>&lt;scriptingNews&gt;</quote>
+format.</para>
+
+<para>The basic concept of all &RSS; files is to provide a
+clean, simple and portable way to distribute web content, in particular news:
+the news sites provide an &RSS; file which basically contains
+a set of records, and each record consists of a headline and a
+&URL; which points to the complete article. The
+&RSS; file also contains other general information about the
+particular news site, such as its name and the homepage, which is evaluated
+by &knewsticker;.</para>
+
+<para>Nowadays there are a few additional, more sophisticated versions of the
+&RSS; format
+(<ulink url="http://backend.userland.com/rss091">0.91</ulink>,
+<ulink url="http://backend.userland.com/rss092">0.92</ulink>,
+<ulink url="http://backend.userland.com/rss093">0.93</ulink>,
+<ulink url="http://web.resource.org/rss/1.0/">1.0</ulink> and the current
+format version
+<ulink url="http://backend.userland.com/rss">2.0</ulink>) but the first two
+versions still make up about 85% of the files provided on the web. Nevertheless,
+all versions up to 2.0 can be processed with &knewsticker;!</para>
+
+<para>Of course, this is only a short and highly incomplete attempt at
+explaining the basic ideas behind &RSS; files. If you're
+interested in this topic, you might want to visit any of the following links
+which point to further and more complete sources on this:</para>
+
+<variablelist>
+<varlistentry>
+	<term><ulink url="http://www.webreference.com/authoring/languages/xml/rss/intro/">http://www.webreference.com/authoring/languages/xml/rss/intro/</ulink></term>
+	<listitem><para>A very pragmatic introduction to the &RSS;
+	format, with concrete examples and guidelines. Together with the
+	authoritative specifications, this makes a good guide for people
+	who are thinking
+	about providing an &RSS; newsfeed on their home
+	page.</para></listitem>
+</varlistentry>
+<varlistentry>
+	<term><ulink url="http://www.oreillynet.com/rss/">http://www.oreillynet.com/rss/</ulink></term>
+	<listitem><para>The &RSS; page from O'Reilly features a
+	lot of general articles about employing and using &RSS; files,
+	up to date news about the &RSS; development community as well
+	as vital information for web developers who are considering taking advantage of
+	&RSS;.</para></listitem>
+</varlistentry>
+<varlistentry>
+	<term><ulink url="http://blogspace.com/rss/">http://blogspace.com/rss/</ulink></term>
+	<listitem><para>This page is another excellent source of news about the
+	&RSS; development, which is especially interesting to
+	developers working with &RSS;-based technology.</para></listitem>
+</varlistentry>
+<varlistentry>
+	<term><ulink url="http://www.w3.org/RDF/">http://www.w3.org/RDF/</ulink></term>
+	<listitem><para><emphasis>The</emphasis> authoritative source about
+	<acronym>RDF</acronym>, an &XML;-based language from which
+	modern &RSS; versions are derived, published by the
+	<ulink url="http://www.w3.org">World Wide Web Consortium</ulink>. It features
+	a comprehensive list of links to other sites on the topic as well as a timeline
+	of the <acronym>RDF</acronym> development, an overview over the architecture, an
+	archive with articles about <acronym>RDF</acronym> as well as a carefully
+	assembled list of tools for developers who intend to work with
+	<acronym>RDF</acronym>.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>Developers will also want to check the authoritative specifications for
+the various &RSS; versions:</para>
+
+<orderedlist>
+<title>&RSS; Specifications</title>
+<listitem><para>
+	Version 0.90: <ulink url="http://www.purplepages.ie/rss/netscape/rss0.90.html">http://www.purplepages.ie/rss/netscape/rss0.90.html</ulink>
+</para></listitem>
+<listitem><para>
+	Version 0.91: <ulink url="http://backend.userland.com/rss091">http://backend.userland.com/rss091</ulink>
+</para></listitem>
+<listitem><para>
+	Version 0.92: <ulink url="http://backend.userland.com/rss092">http://backend.userland.com/rss092</ulink>
+</para></listitem>
+<listitem><para>
+	Version 0.93: <ulink url="http://backend.userland.com/rss093">http://backend.userland.com/rss093</ulink>
+</para></listitem>
+<listitem><para>
+	Version 1.0: <ulink url="http://web.resource.org/rss/1.0/">http://web.resource.org/rss/1.0/</ulink>
+</para></listitem>
+<listitem><para>
+	Version 2.0: <ulink url="http://backend.userland.com/rss">http://backend.userland.com/rss</ulink>
+</para></listitem>
+</orderedlist>
+
+<para>If you find any other sites or documents on this topic, and think they are
+worth being mentioned here, don't hesitate to send them to &Frerich.Raabe;
+&Frerich.Raabe.mail; so that they can be included in this document and
+help everybody.</para>
+
+<para>Thank you very much!</para>
+</sect1>
+</chapter>
+
+<chapter id="starting-knewsticker">
+<title>Starting &knewsticker;</title>
+
+<screenshot>
+	<screeninfo>Here is a screenshot of &knewsticker; in &kde;'s
+	panel.</screeninfo>
+	<mediaobject>
+		<imageobject><imagedata fileref="knewsticker-kicker.png" format="PNG"/></imageobject>
+		<textobject>
+			<phrase>Here is a screenshot of &knewsticker; in &kde;'s
+			panel.</phrase>
+		</textobject>
+	</mediaobject>
+</screenshot>
+
+<para>
+&knewsticker; is started like every other &kicker; applet. You just have to add
+it to the panel (or any child panel of the main one). To do so, just right-click
+on the &kde; panel and choose <menuchoice><guimenu>Add</guimenu>
+<guisubmenu>Applet</guisubmenu><guimenuitem>&knewsticker;</guimenuitem>
+</menuchoice>.</para>
+
+<screenshot>
+	<screeninfo>Here is a screenshot of &knewsticker; in its own child
+	panel.</screeninfo>
+	<mediaobject>
+		<imageobject><imagedata fileref="knewsticker-childpanel.png" format="PNG"/></imageobject>
+		<textobject>
+			<phrase>Here is a screenshot of &knewsticker; in its own child
+			panel.</phrase>
+		</textobject>
+	</mediaobject>
+</screenshot>
+
+<para>Another good way to use &knewsticker; is to put it into its own child
+panel. Just add a new child panel by choosing <menuchoice><guimenu>Add</guimenu>
+<guisubmenu>Extension</guisubmenu><guimenuitem>Child Panel</guimenuitem>
+</menuchoice> from the panel menu;. Now you can simply right-click on the child
+panel and select &knewsticker; as described above.</para>
+
+<screenshot>
+	<screeninfo>Here is a screenshot of &knewsticker; in its own
+	window.</screeninfo>
+	<mediaobject>
+		<imageobject><imagedata fileref="knewsticker-ownwindow.png" format="PNG"/></imageobject>
+		<textobject>
+			<phrase>Here is a screenshot of &knewsticker; in its own
+			window.</phrase>
+		</textobject>
+	</mediaobject>
+</screenshot>
+
+<para>A third, popular, way to run &knewsticker; is by selecting <menuchoice>
+<guimenu>Internet</guimenu><guimenuitem>&knewsticker; (News
+Ticker)</guimenuitem></menuchoice> from the <guilabel>K</guilabel> menu. This
+will start &knewsticker; and make it run in its own window which you can then
+resize and move around as you wish.</para>
+</chapter>
+
+<chapter id="configuration">
+<title>Configuring &knewsticker;</title>
+
+<para>You can access &knewsticker;'s configuration dialog by right-clicking
+onto the scroll text, or by clicking on the button with the arrow on it and
+choosing the entry labelled <guimenuitem><inlinemediaobject><imageobject>
+<imagedata fileref="preferences-icon.png" format="PNG"/></imageobject>
+</inlinemediaobject> Preferences</guimenuitem> in the menu.</para>
+
+<sect1 id="config-general">
+<title>General Options</title>
+
+<screenshot>
+	<screeninfo>This is what the <guilabel>General</guilabel> tab of the
+	preferences dialog looks like.</screeninfo>
+	<mediaobject>
+		<imageobject><imagedata fileref="kcmnewsticker-general.png" format="PNG"/></imageobject>
+		<textobject>
+			<phrase>This is what the <guilabel>General</guilabel> tab of the
+			preferences dialog looks like.</phrase>
+		</textobject>
+	</mediaobject>
+</screenshot>
+
+<para>Here you can define how fast the text should be scrolled around, what it
+should look like as well as other options for the applet. Here is a brief info
+on what each of the switches and buttons on this tab does:</para>
+
+<variablelist>
+<varlistentry>
+	<term><guilabel>Mousewheel sensitivity:</guilabel></term>
+	<listitem>
+		<para>This slider allows you to define how fast/slow the text should be
+		scrolled when using the mousewheel.</para>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel>News query interval</guilabel></term>
+	<listitem>
+		<para>Here you can define in what intervals &knewsticker; queries the
+		configured news sources for new headlines. This depends generally on
+		how fast you'd like to hear about news and how much load you want to
+		put on the network:</para>
+		<itemizedlist>
+			<listitem>
+				<para>A lower value (lower than 15 minutes) enables you to be
+				notified about news very quickly if you want or need to. Please
+				note, that it increases the network traffic significantly,
+				though. Therefore, such low values shouldn't be used if you
+				query popular news sites (such as
+				<ulink url="http://slashdot.org">Slashdot</ulink> or
+				<ulink url="http://freshmeat.net">Freshmeat</ulink>) as they
+				have generally already enough work with processing the incoming
+				queries.</para>
+			</listitem>
+			<listitem>
+				<para>A higher value (higher than 45 minutes) won't make you
+				hear about news that quick. For non-time-critical applications,
+				it should be suitable, though. The positive aspect of longer
+				intervals is that only very little load is put on the network;
+				this saves resources and nerves, for you and the system
+				administrators of the news sites you query.</para>
+			</listitem>
+		</itemizedlist>
+		<tip><para>The default value (30 minutes) should be appropriate and
+		reasonable in most cases.</para></tip>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel>Use custom names for news sites</guilabel></term>
+	<listitem>
+		<para>Check this box to make the news ticker use the names you
+		specified in the list of news sources (available on the tab
+		labeled <guilabel>News sources</guilabel>) instead of the ones
+		the news sites themselves report. This can be handy for news sites
+		which report a very long or useless name.</para>
+	</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="config-newssources">
+<title>Configuration of the news sources</title>
+
+<screenshot>
+	<screeninfo>This is what the <guilabel>News Sources</guilabel> tab of the
+	preferences dialog looks like.</screeninfo>
+	<mediaobject>
+		<imageobject><imagedata fileref="kcmnewsticker-newssources.png" format="PNG"/></imageobject>
+		<textobject>
+			<phrase>This is what the <guilabel>News Sources</guilabel> tab of
+			the preferences dialog looks like.</phrase>
+		</textobject>
+	</mediaobject>
+</screenshot>
+
+<para>On this tab you can manage and maintain the list of news sites
+&knewsticker; queries for news. Click on any entry with the right mouse button
+to open a context menu which lets you remove the current entry, or add a new
+entry. At the bottom of the page you can also find three buttons which have
+the same effect.</para>
+
+<sect2>
+<title>Adding a news site</title>
+<para>There are four ways to <emphasis>add</emphasis> a new news site to the
+list:</para>
+<itemizedlist>
+	<listitem>
+		<para>You can click on the button at the bottom labeled
+		<guilabel>Add...</guilabel>.</para>
+	</listitem>
+	<listitem>
+		<para>You can click with the right mouse button on the table and choose
+		<guimenuitem>Add news source</guimenuitem>.</para>
+	</listitem>
+	<listitem>
+		<para>You can drag any &RSS; file from another
+		application (such as &konqueror;) onto the table. This adds a new entry
+		to the list, sets the name to <quote>Unknown</quote> and sets the
+		maximum number of articles to 10.</para>
+	</listitem>
+	<listitem>
+		<para>And finally, you can just click on any &RSS;
+		file in the &konqueror; filemanager to have it added to the list
+		immediately.</para>
+	</listitem>
+</itemizedlist>
+<para>Either way will cause the <link linkend="config-news-site-dialog">News site
+dialog</link> to show up, presenting you with a form to enter the properties of
+the news site to add.</para>
+</sect2>
+
+<sect2>
+<title>Modifying an existing news site</title>
+<para>There are two ways to adjust the properties of an existing news
+site:</para>
+<itemizedlist>
+	<listitem>
+		<para>You can click on the button at the bottom labeled
+		<guilabel>Modify...</guilabel>.</para>
+	</listitem>
+	<listitem>
+		<para>You can right-click with the right mouse button on the news site
+		you'd like to edit and choose <guimenuitem>Modify '...'</guimenuitem>
+		from the menu.</para>
+	</listitem>
+</itemizedlist>
+<para>No matter which way you chose, it will cause the
+<link linkend="config-news-site-dialog">News site dialog</link> to pop up,
+showing the properties of the selected news site.</para>
+</sect2>
+
+<sect2>
+<title>Removing a news site</title>
+<para>Of course, you want to <emphasis>remove</emphasis> a news source from
+the list sometimes. To do this, you can either</para>
+<itemizedlist>
+	<listitem>
+		<para>click on the button at the bottom labeled
+		<guilabel>Remove</guilabel>, or</para>
+	</listitem>
+	<listitem>
+		<para>right-click with the right mouse button on the news site
+		you'd like to edit and choose <guimenuitem>Remove '...'</guimenuitem>
+		from the menu.</para>
+	</listitem>
+</itemizedlist>
+<para>In both cases, a confirmation box will pop up and make sure you didn't
+select the wrong entry.</para>
+<tip><para>You can also remove multiple news sites at once by holding &Ctrl;
+while clicking on the entries you wouldd like to remove, or by clicking the
+<mousebutton>left</mousebutton> mousebutton and dragging the mouse over all
+the entries you'd like to select.</para></tip>
+</sect2>
+
+<sect2 id="config-news-site-dialog">
+<title>The news site dialog</title>
+
+<screenshot>
+	<screeninfo>This is what the dialog for adding and editing news sites looks
+	like.</screeninfo>
+	<mediaobject>
+		<imageobject><imagedata fileref="kcmnewsticker-newssitedialog.png" format="PNG"/></imageobject>
+		<textobject>
+			<phrase>This is what the dialog for adding and editing news sites
+			looks like.</phrase>
+		</textobject>
+	</mediaobject>
+</screenshot>
+
+<para>When adding or modifying a news site, the news site dialog (shown above)
+pops up and provides input facilities to edit the various properties of a news
+site:</para>
+
+<variablelist>
+<varlistentry>
+	<term><guilabel>Name:</guilabel></term>
+	<listitem>
+		<para>This is the name of the news source.</para>
+		<note><para>This text will only be used if <guilabel>Use custom names
+		for news sites</guilabel> on the tab labeled
+		<link linkend="config-general">General</link> is
+		activated.</para></note>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel>Source file:</guilabel></term>
+	<listitem>
+		<para>Here you can set the &URL; which references
+		the &RSS; file of this news site; this can either
+		be a local file, or a file saved on a remote server. You can also
+		click on the button at the right to open a convenient file-selection
+		dialog and browse to the file you would like to use, instead of typing
+		the &URL; by hand.</para>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel>The file is a program</guilabel></term>
+	<listitem>
+		<para>If this file is checked, &knewsticker; will not assume that the
+		&URL; (which was specified in the <guilabel>Source
+		file</guilabel> field) references an &RSS; file, but
+		rather that the &URL; refers a program (usually a
+		script). When querying this news site, &knewsticker; will execute the
+		program and treat whatever the program prints to stdout as
+		&RSS; markup. This is very convenient for conversion
+		scripts which download an &HTML; file and process it,
+		producing &RSS; markup which is suitable for use with
+		&knewsticker;.</para>
+		<tip><para>You can find some scripts which &eg; download stock data in
+		the kdeaddons module, in the
+		<filename class="directory">knewsticker-scripts</filename>
+		directory.</para></tip>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel>Category:</guilabel></term>
+	<listitem>
+		<para>Here you can specify into which category the news site belongs.
+		Arranging the news sites into categories makes it much easier to
+		maintain large lists of news sites.</para>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel>Max. articles:</guilabel></term>
+	<listitem>
+		<para>This option lets you define how many articles &knewsticker; will
+		cache for this news site; the value will never be exceeded.</para>
+		<para>This is particularly handy for news sites which provide only
+		three news items at once, but you'd like to see the last ten items (for
+		instance); &knewsticker; will always download the three items and merge
+		them into its list, caching the last seven items.</para>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel>Icon:</guilabel></term>
+	<listitem>
+		<para>Here you can specify a &URL; to an image file
+		(preferably 16x16 pixels in size) which should be used for this news
+		site. Icons make it much easier to distinguish multiple news sites, and
+		see which news site a headline appeared on as it scrolls by in
+		&knewsticker;.</para>
+	</listitem>
+</varlistentry>
+</variablelist>
+
+<para>At the button you will find the usual buttons. One of them deserves an
+extra note: clicking on the <guilabel>Suggest</guilabel> button will make
+&knewsticker; try to guess suitable values for most of the fields if you
+specify a &URL; to a valid source file.</para>
+
+<para>This means that you can usually just paste a &URL; to
+an &RSS; file in the input field labeled <guilabel>Source
+file</guilabel>, press the <guilabel>Suggest</guilabel> button and then modify
+the suggested values as needed.</para>
+</sect2>
+</sect1>
+
+<sect1 id="config-filters">
+<title>Filters</title>
+
+<screenshot>
+	<screeninfo>This is what the <guilabel>Filters</guilabel> tab of the
+	preferences dialog looks like.</screeninfo>
+	<mediaobject>
+		<imageobject><imagedata fileref="kcmnewsticker-filters.png" format="PNG"/></imageobject>
+		<textobject>
+			<phrase>This is what the <guilabel>Filters</guilabel> tab of
+			the preferences dialog looks like.</phrase>
+		</textobject>
+	</mediaobject>
+</screenshot>
+
+<para>This tab allows you to define various filters which should be applied
+before showing the headlines in the scroll text.</para>
+
+<note><para>These filters only affect the headlines which are shown in the
+scrolltext; the menu will always show all of the headlines.</para></note>
+<para>The major part of the tab is occupied by a table which lists the
+currently configured filters. Each filter has a small checkable box - checking
+that box enables the filter, unchecking it temporarily disables it without
+removing it from the list.</para>
+
+<para>By default there are no filters, so chances are that the table is
+completely empty for you. Of course, this dialog provides you with ways
+to add new filters, and manage them in general:</para>
+
+<itemizedlist>
+<listitem>
+	<para>To <emphasis>add</emphasis> a filter, simply enter the filter
+	properties (see <link linkend="filter-components">Filter
+	Components</link> for a detailed description of the various filter
+	properties) using the input fields in the box labeled <guilabel>Filter
+	properties</guilabel> and then press the button labeled
+	<guilabel>Add</guilabel>.</para>
+</listitem>
+<listitem>
+	<para>To <emphasis>modify</emphasis> an existing filter, select the
+	filter you would like to edit in the table by left-clicking on it and
+	then change its properties in the box at the bottom.</para>
+</listitem>
+<listitem>
+	<para>To <emphasis>remove</emphasis> a filter, select it in the table
+	and then press the button labeled <guilabel>Remove</guilabel>.</para>
+</listitem>
+</itemizedlist>
+
+<sect2 id="filter-components">
+<title>Filter Components</title>
+
+<para>Each filter consists of four components:</para>
+
+<orderedlist>
+<title>Filter Components</title>
+<listitem>
+	<para>Action &ndash; this can be either <guilabel>Show</guilabel> or
+	<guilabel>Hide</guilabel> and defines what should happen to a headline
+	in case this filter matches.</para>
+</listitem>
+<listitem>
+	<para>News sources &ndash; here you can define whether the filter affects only
+	single news sources, or whether this filter should be applied to the
+	headlines of all news sources.</para>
+</listitem>
+<listitem>
+	<para>Condition &ndash; this is a verb which defines, together with the
+	Expression, whether a filter matches. A condition can be &eg;
+	<guilabel>contains</guilabel>, <guilabel>doesn't equal</guilabel> or
+	<guilabel>matches</guilabel>. See below for a more detailed
+	description.</para>
+</listitem>
+<listitem>
+	<para>Expression - this is a user-defined string which forms the body
+	of the filter, together with the Condition. See below for a more detailed
+	description of this component.</para>
+</listitem>
+</orderedlist>
+
+<para>All these components can be configured using the facilities in the frame
+labeled <guilabel>Filter properties</guilabel>. The possible states of the
+Condition component deserve a special explanation:</para>
+
+<itemizedlist>
+<listitem>
+	<para><guilabel>contains</guilabel>, <guilabel>doesn't contain</guilabel>:
+	this filter matches if the headline contains / doesn't contain the
+	specified expression.</para>
+	<note><para>The expression isn't treated case-sensitively, so the expressions
+	<quote>KDE</quote>, <quote>kDE</quote> or <quote>kde</quote> will all match
+	headlines which contain <quote>KDE</quote>.</para></note>
+</listitem>
+<listitem>
+	<para><guilabel>equals</guilabel>, <guilabel>doesn't equal</guilabel>:
+	this filter matches if the headline equals / doesn't equal the
+	specified expression.</para>
+	<note><para>The expression is treated case-sensitively, so of the expressions
+	<quote>&Linux;</quote>, <quote>linux</quote> or <quote>LINUX</quote>, only the
+	first will match <quote>&Linux;</quote>.</para></note>
+</listitem>
+<listitem>
+	<para><guilabel>matches</guilabel>: using this condition will make
+	&knewsticker; treat the given expression as a <quote>regular
+	expression</quote>. For further information on regular expressions you
+	might want to read
+	<ulink url="http://www.evolt.org/article/rating/20/22700/">this
+	article</ulink> which was published at
+	<ulink url="http://www.evolt.org">www.evolt.org</ulink>.</para>
+</listitem>
+</itemizedlist>
+</sect2>
+</sect1>
+
+<sect1 id="config-scroller">
+<title>Scroller Preferences</title>
+
+<screenshot>
+	<screeninfo>This is what the <guilabel>Scroller Preferences</guilabel> tab
+	of the preferences dialog looks like.</screeninfo>
+	<mediaobject>
+		<imageobject><imagedata fileref="kcmnewsticker-scrollerprefs.png" format="PNG"/></imageobject>
+		<textobject>
+			<phrase>This is what the <guilabel>Scroller Preferences</guilabel>
+			tab of the preferences dialog looks like.</phrase>
+		</textobject>
+	</mediaobject>
+</screenshot>
+
+<para>This tab lets you define various options which affect &knewsticker;'s
+scroll text:</para>
+
+<variablelist>
+<varlistentry>
+	<term><guilabel>Scrolling speed</guilabel></term>
+	<listitem>
+		<para>This slider lets you define how fast the scrolltext should be
+		scrolling. If you have rather little space on your taskbar (and
+		therefore a rather small news ticker), you should probably set this
+		to a lower value so that you have a chance to read the headlines.
+		For wider news tickers (and better eyes), a faster text is probably
+		appropriate so that you have to wait for the next headline only as
+		little as possible.</para>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel>Direction of scrolling</guilabel></term>
+	<listitem>
+		<para>These options allow you to define in what direction the text
+		should be scrolled, &eg; to the left or to the right, upwards or
+		downwards. You can also rotate the text by 90 or 270 degrees here,
+		which is not exactly readable but it makes sense for vertically
+		aligned panels.</para>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel>Scrolltext font</guilabel></term>
+	<listitem>
+		<para>Click on the button at the right labeled <guilabel>Choose
+		Font...</guilabel> to choose the font which will be used for the
+		scrolling text.</para>
+		<tip><para>Certain fonts are harder to read than others, especially
+		when they are used for a scrolltext, so you should probably choose a font
+		which can even easily be read if it's moving.</para></tip>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel>Foreground color</guilabel></term>
+	<listitem>
+		<para>Click this button open a convenient color-selection dialog which
+		lets you choose the color which will be used for the foreground of the
+		scrolling text (&ie; the color of the text itself).</para>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel>Background color</guilabel></term>
+	<listitem>
+		<para>Click this button to open a convenient color-selection dialog
+		which lets you choose the color which will be used for the background
+		of the scrolling text.</para>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel>Highlighted color</guilabel></term>
+	<listitem>
+		<para>Click this button to open a convenient color-selection dialog
+		which lets you choose the color which will be used for the color of
+		the headlines when they are highlighted (when you move the mouse over
+		them).</para>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel>Scroll the most recent headlines only</guilabel></term>
+	<listitem>
+		<para>Check this button to make the scrolltext show just the most
+		recent headline for each news site, instead of showing every
+		headline available from every news site.</para>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel>Show icons</guilabel></term>
+	<listitem>
+		<para>Checking this box will make &knewsticker; show an icon (if
+		available) in front of each headline which is scrolled along; this
+		makes determining which news site provided each headline much
+		easier.</para>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel>Temporarily slowed scrolling</guilabel></term>
+	<listitem>
+		<para>Check this box to make &knewsticker; slow the scrolling down
+		when you move the mouse cursor over the scrolling text. This makes
+		clicking on items and dragging away the icons (if enabled) a lot
+		easier.</para>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel>Underline highlighted headline</guilabel></term>
+	<listitem>
+		<para>Check this box to have the currently highlighted headline
+		(&ie; the headline which is currently under the mouse cursor)
+		underlined.</para>
+	</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+</chapter>
+
+<chapter id="using-knewsticker">
+<title>Using &knewsticker;</title>
+
+<para>Using &knewsticker; is fairly straightforward and should give you no
+big problems, assuming that you have already
+<link linkend="configuration">configured it</link>. No matter
+whether you are running &knewsticker; in the main panel, in its own child
+panel or in its own window, it appears as an area with a scrolling text and
+a button with a small arrow next to it.</para>
+
+<sect1 id="applet-descr">
+<title>The Main Interface</title>
+
+<para>The area (it is white by default, but you can change the background
+color easily using the preferences dialog) with the scrolling text in it is
+called the <quote>news scroller</quote>. It keeps scrolling the downloaded
+headlines (or just the most recent headlines) continuously and provides easy
+access to the articles. If you see an interesting article, just click on it
+to open the &konqueror; web browser, showing the full article which belongs to
+the headline you clicked on. If you feel that a possibly interesting headline
+just scrolled out of view, you have some ways to influence the
+scrolling:</para>
+
+<itemizedlist>
+	<listitem>
+		<para>You can click on the news scroller with the
+		<mousebutton>left</mousebutton> mouse button and move the mouse around
+		(while holding the <mousebutton>left</mousebutton> mouse button pressed
+		down). The news scroller will continue scrolling as usual if you release
+		the left mouse button again.</para>
+	</listitem>
+	<listitem>
+		<para>If you own a so-called <quote>wheel mouse</quote>, you can use
+		the wheel on your mouse to scroll the headlines back and forth.</para>
+	</listitem>
+</itemizedlist>
+
+<para>There's also a very powerful <link linkend="contextmenu-descr">context
+menu</link>, which you can access either by clicking on the news scroller with
+the <mousebutton>right</mousebutton> mouse button, or by clicking on the
+arrow button with the <mousebutton>left</mousebutton> button. This context menu
+is the most interesting part of the applet, as it contains about all the
+functionality.</para>
+</sect1>
+
+<sect1 id="contextmenu-descr">
+<title>The Context Menu</title>
+
+<screenshot>
+	<screeninfo>This is what the context menu of &knewsticker; looks like, when
+	using just the default news sites.</screeninfo>
+	<mediaobject>
+		<imageobject><imagedata fileref="contextmenu.png" format="PNG"/></imageobject>
+		<textobject>
+			<phrase>This is what the context menu of &knewsticker; looks like,
+			when using just the default news sites.</phrase>
+		</textobject>
+	</mediaobject>
+</screenshot>
+
+<para>The context menu is basically split into two functional parts:</para>
+
+<para>The upper part shows a list of entries, each entry having a small icon like
+this <inlinemediaobject><imageobject>
+<imagedata fileref="newssite-icon.png" format="PNG"/></imageobject>
+</inlinemediaobject> next to it. This list represents
+the list of currently configured news sites. You can click on any of the news
+sources to open another menu which contains a listing of headlines which are
+available for that particular news site as well as an entry labeled <guilabel>
+<inlinemediaobject><imageobject><imagedata fileref="checknews-icon.png"
+format="PNG"/></imageobject></inlinemediaobject> Check news</guilabel> to
+refresh the headline list for this news site. Each of the headlines has an
+<inlinemediaobject><imageobject>
+<imagedata fileref="oldarticle-icon.png" format="PNG"/></imageobject>
+</inlinemediaobject> icon next to it indicating that that you
+have read that article already or the <inlinemediaobject><imageobject>
+<imagedata fileref="newarticle-icon.png" format="PNG"/></imageobject>
+</inlinemediaobject> if it is still
+unread.</para>
+
+<para>The lower part currently shows five entries (explained from top to
+bottom):</para>
+
+<variablelist>
+<varlistentry>
+	<term><guilabel><inlinemediaobject><imageobject><imagedata fileref="checknews-icon.png" format="PNG"/></imageobject></inlinemediaobject> Check news</guilabel></term>
+	<listitem>
+		<para>This entry has a little <inlinemediaobject><imageobject>
+		<imagedata fileref="checknews-icon.png" format="PNG"/></imageobject>
+		</inlinemediaobject> next to it. If you want to force &knewsticker;
+		to check the configured news sites for new articles, you can click
+		here.</para>
+		<note><para>This does not reset the internal timer which queries the
+		news sites for new headlines automatically in certain
+		intervals.</para></note>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel>Offline mode</guilabel></term>
+	<listitem>
+		<para>This entry in the context menu has no icon associated with it.
+		Click this button to enable a special <quote>offline mode</quote>
+		which pauses the internal timer for querying the news sites and
+		prevents any automatic download of new headlines. The offline mode
+		comes in handy if you have to leave your computer for a while
+		during which the system isn't connected to the Internet, as it
+		saves you from all the error messages which pop up if any of the
+		news sites couldn't be connected.</para>
+		<tip><para>You can still force a reload for single news sites as
+		well as for all the news sites by selecting the respective
+		<guilabel><inlinemediaobject><imageobject><imagedata
+		fileref="checknews-icon.png" format="PNG"/></imageobject>
+		</inlinemediaobject> Check news</guilabel> entry.</para></tip>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel><inlinemediaobject><imageobject><imagedata fileref="help-icon.png" format="PNG"/></imageobject></inlinemediaobject> Help</guilabel></term>
+	<listitem>
+		<para>This entry is marked with a small <inlinemediaobject>
+		<imageobject><imagedata fileref="help-icon.png" format="PNG"/>
+		</imageobject></inlinemediaobject>. Clicking on this entry opens
+		the &knewsticker; documentation (which you're reading in this
+		moment) which details all the features and abilities of
+		&knewsticker;.</para>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel><inlinemediaobject><imageobject><imagedata fileref="knewsticker-icon.png" format="PNG"/></imageobject></inlinemediaobject> About</guilabel></term>
+	<listitem>
+		<para>This entry is marked with a small <inlinemediaobject>
+		<imageobject><imagedata fileref="knewsticker-icon.png" format="PNG"/>
+		</imageobject></inlinemediaobject>. Clicking on this entry opens
+		a small dialog showing who's to blame for &knewsticker; and credits
+		people who contributed significant enhancements for
+		it.</para>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><guilabel><inlinemediaobject><imageobject><imagedata fileref="preferences-icon.png" format="PNG"/></imageobject></inlinemediaobject> Preferences</guilabel></term>
+	<listitem>
+		<para>This entry is easily recognizable due to the <inlinemediaobject>
+		<imageobject><imagedata fileref="preferences-icon.png" format="PNG"/>
+		</imageobject></inlinemediaobject> icon which is next to it. Select
+		this entry to open the <link linkend="configuration">preferences
+		dialog</link> which lets you customize all of the properties of
+		&knewsticker;</para>
+	</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+</chapter>
+
+<chapter id="faq">
+<title>Frequently Asked Questions</title>
+
+&reporting.bugs;
+
+<qandaset id="faqlist">
+<qandaentry>
+	<question>
+		<para>Where do I find the &RSS; file for the news
+		site XYZ?</para>
+	</question>
+	<answer>
+		<para>It's possible that the news site you're referring to
+		doesn't provide any &RSS; file at all! Here's a short list of
+		websites which provide thousands of &RSS; feeds, sorted by
+		language and/or topic - for free:</para>
+
+		<itemizedlist>
+		<listitem><para>
+		<ulink url="http://www.webreference.com/services/news">WebReference.com</ulink>
+		</para></listitem>
+		<listitem><para>
+		<ulink url="http://www.newsisfree.com/syndicate.php">NewsIsFree</ulink>
+		</para></listitem>
+		<listitem><para>
+		<ulink url="http://w.moreover.com/categories/category_list_rss.html">MoreOver</ulink>
+		</para></listitem>
+		</itemizedlist>
+
+		<para>If you have found any interesting news sites which provide
+		such a backend, don't hesitate to send them to &Frerich.Raabe;
+		&Frerich.Raabe.mail; so that they can be included in
+		future releases. Thank you!</para>
+	</answer>
+</qandaentry>
+<qandaentry>
+	<question>
+		<para>How can I make &knewsticker; open articles in another browser
+		(&eg; Mozilla)?</para>
+	</question>
+	<answer>
+		<para>&knewsticker; will use whatever browser you have associated with
+		the text/html &MIME; type; the default browser used for viewing
+		&HTML; pages is &konqueror;.</para>
+		<para>You can find the dialog for changing this association by opening
+		the &kde; control center and browsing to <menuchoice><guimenu>KDE
+		Components</guimenu> <guisubmenu>File
+		Associations</guisubmenu></menuchoice>.</para>
+	</answer>
+</qandaentry>
+</qandaset>
+</chapter>
+
+<chapter id="credits">
+<title>Credits And License</title>
+
+<para>&knewsticker;</para>
+
+<para>Program copyright 2000, 2001, 2002, 2003 &Frerich.Raabe;
+&Frerich.Raabe.mail;</para>
+
+<para>Contributors:</para>
+
+<itemizedlist>
+<listitem>
+	<para>Malte Starostik <email>malte.starostik@t-online.de</email></para>
+</listitem>
+<listitem>
+	<para>&Wilco.Greven; &Wilco.Greven.mail;</para>
+</listitem>
+<listitem>
+	<para>Adriaan de Groot <email>adrig@sci.kun.nl</email></para>
+</listitem>
+</itemizedlist>
+
+<para>Documentation copyright 2001, 2002, 2003 &Frerich.Raabe;
+&Frerich.Raabe.mail;</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+&underFDL;
+&underBSDLicense;
+</chapter>
+
+<glossary id="glossary">
+<title>Glossary</title>
+
+<para>This chapter is intended to explain the various acronyms which have been
+used throughout the &knewsticker; documentation. If you feel any acronyms or
+terms are missing here, please don't hesitate to send an email to &Frerich.Raabe;
+&Frerich.Raabe.mail; so that they can be added. Thank you!</para>
+
+<glossentry id="gloss-rdf">
+	<glossterm>RDF</glossterm>
+	<glossdef>
+		<para>Resource Description Framework. A language derived from
+		&XML; which describes metadata. Commonly used as a
+		backend format for articles and other publications. For more detailed
+		information on <acronym>RDF</acronym> files, you might want to go
+		directly to the <ulink url="http://www.w3.org/RDF/">official page on
+		<acronym>RDF</acronym> files</ulink> at the
+		<ulink url="http://www.w3.org">World Wide Web
+		Consortium</ulink>.</para>
+	</glossdef>
+</glossentry>
+<glossentry id="gloss-rss">
+	<glossterm>&RSS;</glossterm>
+	<glossdef>
+		<para>The <acronym>RDF</acronym> Site Summary is actually an
+		extension to the <acronym>RDF</acronym> language. Quoting the official
+		<ulink url="http://www.purl.org/rss/1.0/">&RSS; v1.0
+		specification</ulink>:</para>
+		<para><quote><acronym>RDF</acronym> Site Summary
+		(&RSS;) is a lightweight multipurpose extensible
+		metadata description and syndication format. &RSS; is
+		an &XML; application, conforms to the
+		<acronym>W3C</acronym>'s <acronym>RDF</acronym> specification and is
+		extensible via &XML;-namespace and/or
+		<acronym>RDF</acronym> based modularization.</quote></para>
+	</glossdef>
+</glossentry>
+<glossentry id="gloss-xml">
+	<glossterm>&XML;</glossterm>
+	<glossdef>
+		<para>The Extensible Markup Language is the <quote>universal format
+		for structured documents and data on the Web</quote>. It's a derivative of
+		<acronym>SGML</acronym> which fits the needs of the world wide web. You
+		might want to check the the
+		<ulink url="http://www.w3.org/XML/">Extensible Markup Language</ulink>
+		page at the <ulink url="http://www.w3.org">World Wide Web
+		Consortium</ulink> for further information.</para>
+	</glossdef>
+</glossentry>
+<glossentry id="gloss-w3c">
+	<glossterm>W3C</glossterm>
+	<glossdef>
+		<para>An abbreviation for <quote>World Wide Web Consortium</quote>.
+		Quoting the <ulink url="http://www.w3.org">official homepage</ulink> of
+		the <acronym>W3C</acronym>, <quote>the World Wide Web Consortium
+		(<acronym>W3C</acronym>) develops interoperable technologies
+		(specifications, guidelines, software, and tools) to lead the Web to
+		its full potential as a forum for information, commerce, communication,
+		and collective understanding</quote></para>
+	</glossdef>
+</glossentry>
+<glossentry id="gloss-url">
+	<glossterm>&URL;</glossterm>
+	<glossdef>
+		<para>&URL; stands for <quote>Uniform Resource Locator</quote>,
+		a specially formatted string which can reference resources like images,
+		documents and other things on the Internet. Please refer to the
+		corresponding <ulink url="http://www.w3.org/Addressing/">webpage</ulink>
+		for more detailed information on this topic.</para>
+	</glossdef>
+</glossentry>
+<glossentry id="gloss-dcop">
+	<glossterm>&DCOP;</glossterm>
+	<glossdef>
+		<para>The Desktop COmmunication Protocol is a way for applications
+		to communicate to each other. For instance, &knewsticker;'s
+		<link linkend="configuration">configuration dialog</link> uses
+		&DCOP; to tell the applet itself about the current
+		configuration.</para>
+		<para>&knewsticker; provides an extensive
+		<link linkend="develinfo">&DCOP; interface</link>,
+		which makes it possible to control many of &knewsticker;'s functions
+		from the commandline.</para>
+		<para>For more detailled information on &DCOP;
+		you might want to visit
+		<ulink url="http://developer.kde.org/documentation/library/2.0-api/dcop/HOWTO.html">http://developer.kde.org/documentation/library/2.0-api/dcop/HOWTO.html</ulink>
+		for a complete explanation.</para>
+	</glossdef>
+</glossentry>
+</glossary>
+
+<appendix id="develinfo">
+<title>Information For Developers And Advanced Users</title>
+
+<para>&knewsticker; features a currently rather extensive, and steadily growing
+&DCOP; interface. This is not only used to communicate with
+other applications, it makes it possible to control &knewsticker; with a
+shell script as well. The more the interface is extended, the more useful it will
+become and the more flexible &knewsticker; will be controllable from a
+script.</para>
+
+<para>To use these &DCOP; functions you can either use the
+<application>dcop</application> commandline program or use the more convenient
+<application>KDCOP</application> application. Both provide the same
+functionality so it's actually just a matter of taste which program you prefer.
+:-)</para>
+
+<para>This chapter assumes that you're using the commandline program
+<application>dcop</application>. To access &knewsticker;'s
+&DCOP; functions make sure that &knewsticker; is <link
+linkend="starting-knewsticker">started</link> and then just enter something like
+this at the console:</para>
+
+<screen width="40">
+<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>[function]</option></userinput>
+</screen>
+
+<note><para>If an error appears that tells you that <filename>dcop</filename>
+couldn't be found or executed, please check whether the file
+<filename>dcop</filename> exists in
+<filename class="directory">$<envar>KDEDIR</envar>/bin</filename> and make sure its
+permissions are set appropriately.</para></note>
+
+<para>In that command line, just replace <quote>[function]</quote> with the
+appropriate function name, &ie; type</para>
+
+<screen width="40">
+<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>updateNews</option></userinput>
+</screen>
+
+<para>to make &knewsticker; check for new news items and download them if
+necessary.</para>
+
+<sect1 id="dcop-reference">
+<title>&DCOP; Reference</title>
+
+<para>In this section, all methods which are accessible via &knewsticker;'s
+&DCOP; interface are listed.</para>
+
+<variablelist>
+<varlistentry>
+	<term><command>updateNews</command></term>
+	<listitem>
+		<para>This function forces &knewsticker; to update the internal list
+		of articles (&ie; it queries the list of news sources which has been
+		<link linkend="config-newssources">configured</link> for new news) and
+		downloads them when necessary.</para>
+		<note><para>This also works if &knewsticker; is currently in offline
+		mode.</para></note>
+		<para>Example:</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>updateNews</option></userinput>
+		</screen>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><command>reparseConfig</command></term>
+	<listitem>
+		<para>The <command>reparseConfig</command> command makes &knewsticker;
+		reload its configuration from the configuration file. This function is
+		used by the <link linkend="configuration">configuration dialog</link>
+		to talk to &knewsticker; but you can use it if you modified the
+		configuration file by hand.</para>
+		<tip><para>The configuration file is saved in
+		<filename>~/.kde/share/config/knewsticker_appletrc</filename></para></tip>
+		<para>Example:</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>reparseConfig</option></userinput>
+		</screen>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><command>setOfflineMode [bool]</command></term>
+	<listitem>
+		<para>You can call this function to define whether &knewsticker; is
+		currently in the offline mode (&ie; whether &knewsticker; should query
+		the <link linkend="config-newssources">configured news sites</link> for
+		new news).</para>
+		<para>Example:</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>setOfflineMode</option> <option>true</option></userinput>
+		</screen>
+		<para>to enable the offline mode, or type</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>setOfflineMode</option> <option>false</option></userinput>
+		</screen>
+		<para>to disable offline mode.</para>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><command>interval</command></term>
+	<listitem>
+		<para>Returns the currently configured news query interval in
+		minutes.</para>
+		<para>Example:</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>interval</option></userinput>
+			30
+			<prompt>%</prompt>
+		</screen>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><command>scrollingSpeed</command></term>
+	<listitem>
+		<para>Returns the currently configured scrolling speed. The returned
+		scrolling speed is specified in pixels per second.</para>
+		<para>Example:</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>scrollingSpeed</option></userinput>
+			20
+			<prompt>%</prompt>
+		</screen>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><command>mouseWheelSpeed</command></term>
+	<listitem>
+		<para>Returns the number of pixels the scrolltext gets shifted
+		per mousewheel step.</para>
+		<para>Example:</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>mouseWheelSpeed</option></userinput>
+			15
+			<prompt>%</prompt>
+		</screen>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><command>scrollingDirection</command></term>
+	<listitem>
+		<para>Returns an integer which corresponds to the direction the
+		scrolltext is scrolling in:</para>
+		<itemizedlist>
+			<listitem><para>1 = To the left</para></listitem>
+			<listitem><para>2 = To the right</para></listitem>
+			<listitem><para>3 = Upwards</para></listitem>
+			<listitem><para>4 = Downwards</para></listitem>
+			<listitem><para>5 = Upwards, rotated</para></listitem>
+			<listitem><para>6 = Downwards, rotated</para></listitem>
+		</itemizedlist>
+		<para>Example:</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>scrollingDirection</option></userinput>
+			1
+			<prompt>%</prompt>
+		</screen>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><command>customNames</command></term>
+	<listitem>
+		<para>Returns either 'true' or 'false', depending on whether &knewsticker;
+		uses custom names for the news sites.</para>
+		<para>Example:</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>customNames</option></userinput>
+			false
+			<prompt>%</prompt>
+		</screen>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><command>endlessScrolling</command></term>
+	<listitem>
+		<para>Returns either 'true' or 'false', depending on whether &knewsticker;
+		has the endless scrolling option enabled.</para>
+		<para>Example:</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>endlessScrolling</option></userinput>
+			true
+			<prompt>%</prompt>
+		</screen>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><command>scrollMostRecentOnly</command></term>
+	<listitem>
+		<para>Returns either 'true' or 'false', depending on whether &knewsticker;
+		currently only scrolls the most recent headlines for each news
+		site.</para>
+		<para>Example:</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>scrollMostRecentOnly</option></userinput>
+			false
+			<prompt>%</prompt>
+		</screen>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><command>offlineMode</command></term>
+	<listitem>
+		<para>Returns either 'true' or 'false', depending on whether &knewsticker;
+		is currently in offline mode.</para>
+		<para>Example:</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>offlineMode</option></userinput>
+			false
+			<prompt>%</prompt>
+		</screen>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><command>underlineHighlighted</command></term>
+	<listitem>
+		<para>Returns either 'true' or 'false', depending on whether &knewsticker;
+		was told to underline the headline which is currently below the mouse
+		cursor.</para>
+		<para>Example:</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>underlineHighlighted</option></userinput>
+			true
+			<prompt>%</prompt>
+		</screen>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><command>showIcons</command></term>
+	<listitem>
+		<para>Returns either 'true' or 'false', depending on whether &knewsticker;
+		currently shows the icon of the news site each particular headline
+		was published at in front of the headline.</para>
+		<para>Example:</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>showIcons</option></userinput>
+			true
+			<prompt>%</prompt>
+		</screen>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><command>slowedScrolling</command></term>
+	<listitem>
+		<para>Returns either 'true' or 'false', depending on whether &knewsticker;
+		has the <quote>slowed scrolling</quote> feature activated.</para>
+		<para>Example:</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>slowedScrolling</option></userinput>
+			false
+			<prompt>%</prompt>
+		</screen>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><command>foregroundColor</command></term>
+	<listitem>
+		<para>Returns the currently configured foreground color as a string
+		in the format <quote>#rrggbb</quote>, where <quote>rr</quote>,
+		<quote>gg</quote> and <quote>bb</quote> are two-digit hexadecimal
+		values representing the intensity of the red, green and blue components
+		in a scale of 00-ff.</para>
+		<para>Example:</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>foregroundColor</option></userinput>
+			#804000
+			<prompt>%</prompt>
+		</screen>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><command>backgroundColor</command></term>
+	<listitem>
+		<para>Returns the currently configured background color as a string
+		in the format <quote>#rrggbb</quote>, where <quote>rr</quote>,
+		<quote>gg</quote> and <quote>bb</quote> are two-digit hexadecimal
+		values representing the intensity of the red, green and blue components
+		in a scale of 00-ff.</para>
+		<para>Example:</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>backgroundColor</option></userinput>
+			#0030ff
+			<prompt>%</prompt>
+		</screen>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><command>highlightedColor</command></term>
+	<listitem>
+		<para>Returns the currently configured highlight color as a string
+		in the format <quote>#rrggbb</quote>, where <quote>rr</quote>,
+		<quote>gg</quote> and <quote>bb</quote> are two-digit hexadecimal
+		values representing the intensity of the red, green and blue components
+		in a scale of 00-ff.</para>
+		<para>Example:</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>highlightedColor</option></userinput>
+			#000080
+			<prompt>%</prompt>
+		</screen>
+	</listitem>
+</varlistentry>
+<varlistentry>
+	<term><command>newsSources</command></term>
+	<listitem>
+		<para>Returns the list of currently registered news sources. Note that
+		this returns all news sources, not just the selected ones. In the
+		output, each news source name will be printed on a line.</para>
+		<para>Example:</para>
+		<screen width="40">
+			<prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>newsSources</option></userinput>
+			Freshmeat
+			GNOME News
+			dot.kde.org
+			Slashdot.org
+			<prompt>%</prompt>
+		</screen>
+	</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+</appendix>
+
+&documentation.index;
+
+</book>
diff --git a/doc/knewsticker/kcmnewsticker-filters.png b/doc/knewsticker/kcmnewsticker-filters.png
new file mode 100644
index 00000000..6386a113
--- /dev/null
+++ b/doc/knewsticker/kcmnewsticker-filters.png
diff --git a/doc/knewsticker/kcmnewsticker-general.png b/doc/knewsticker/kcmnewsticker-general.png
new file mode 100644
index 00000000..e0b3e58a
--- /dev/null
+++ b/doc/knewsticker/kcmnewsticker-general.png
diff --git a/doc/knewsticker/kcmnewsticker-newssitedialog.png b/doc/knewsticker/kcmnewsticker-newssitedialog.png
new file mode 100644
index 00000000..cc3e0fdf
--- /dev/null
+++ b/doc/knewsticker/kcmnewsticker-newssitedialog.png
diff --git a/doc/knewsticker/kcmnewsticker-newssources.png b/doc/knewsticker/kcmnewsticker-newssources.png
new file mode 100644
index 00000000..da54789c
--- /dev/null
+++ b/doc/knewsticker/kcmnewsticker-newssources.png
diff --git a/doc/knewsticker/kcmnewsticker-scrollerprefs.png b/doc/knewsticker/kcmnewsticker-scrollerprefs.png
new file mode 100644
index 00000000..7f2538b1
--- /dev/null
+++ b/doc/knewsticker/kcmnewsticker-scrollerprefs.png
diff --git a/doc/knewsticker/kcontrol-icon.png b/doc/knewsticker/kcontrol-icon.png
new file mode 100644
index 00000000..7fc0da9b
--- /dev/null
+++ b/doc/knewsticker/kcontrol-icon.png
diff --git a/doc/knewsticker/knewsticker-childpanel.png b/doc/knewsticker/knewsticker-childpanel.png
new file mode 100644
index 00000000..a1eeb83d
--- /dev/null
+++ b/doc/knewsticker/knewsticker-childpanel.png
diff --git a/doc/knewsticker/knewsticker-icon.png b/doc/knewsticker/knewsticker-icon.png
new file mode 100644
index 00000000..714e9834
--- /dev/null
+++ b/doc/knewsticker/knewsticker-icon.png
diff --git a/doc/knewsticker/knewsticker-kicker.png b/doc/knewsticker/knewsticker-kicker.png
new file mode 100644
index 00000000..75bbf87d
--- /dev/null
+++ b/doc/knewsticker/knewsticker-kicker.png
diff --git a/doc/knewsticker/knewsticker-ownwindow.png b/doc/knewsticker/knewsticker-ownwindow.png
new file mode 100644
index 00000000..f0da9e27
--- /dev/null
+++ b/doc/knewsticker/knewsticker-ownwindow.png
diff --git a/doc/knewsticker/newarticle-icon.png b/doc/knewsticker/newarticle-icon.png
new file mode 100644
index 00000000..43b02977
--- /dev/null
+++ b/doc/knewsticker/newarticle-icon.png
diff --git a/doc/knewsticker/newssite-icon.png b/doc/knewsticker/newssite-icon.png
new file mode 100644
index 00000000..a4be959f
--- /dev/null
+++ b/doc/knewsticker/newssite-icon.png
diff --git a/doc/knewsticker/oldarticle-icon.png b/doc/knewsticker/oldarticle-icon.png
new file mode 100644
index 00000000..a16644e7
--- /dev/null
+++ b/doc/knewsticker/oldarticle-icon.png
diff --git a/doc/knewsticker/preferences-icon.png b/doc/knewsticker/preferences-icon.png
new file mode 100644
index 00000000..0c95c52c
--- /dev/null
+++ b/doc/knewsticker/preferences-icon.png