summaryrefslogtreecommitdiffstats
path: root/doc/knewsticker
diff options
context:
space:
mode:
Diffstat (limited to 'doc/knewsticker')
-rw-r--r--doc/knewsticker/Makefile.am4
-rw-r--r--doc/knewsticker/TODO4
-rw-r--r--doc/knewsticker/about-icon.pngbin0 -> 223 bytes
-rw-r--r--doc/knewsticker/checknews-icon.pngbin0 -> 1076 bytes
-rw-r--r--doc/knewsticker/contextmenu.pngbin0 -> 5850 bytes
-rw-r--r--doc/knewsticker/help-icon.pngbin0 -> 510 bytes
-rw-r--r--doc/knewsticker/index.docbook1399
-rw-r--r--doc/knewsticker/kcmnewsticker-filters.pngbin0 -> 27073 bytes
-rw-r--r--doc/knewsticker/kcmnewsticker-general.pngbin0 -> 21593 bytes
-rw-r--r--doc/knewsticker/kcmnewsticker-newssitedialog.pngbin0 -> 14311 bytes
-rw-r--r--doc/knewsticker/kcmnewsticker-newssources.pngbin0 -> 33750 bytes
-rw-r--r--doc/knewsticker/kcmnewsticker-scrollerprefs.pngbin0 -> 26870 bytes
-rw-r--r--doc/knewsticker/kcontrol-icon.pngbin0 -> 2293 bytes
-rw-r--r--doc/knewsticker/knewsticker-childpanel.pngbin0 -> 4353 bytes
-rw-r--r--doc/knewsticker/knewsticker-icon.pngbin0 -> 312 bytes
-rw-r--r--doc/knewsticker/knewsticker-kicker.pngbin0 -> 13451 bytes
-rw-r--r--doc/knewsticker/knewsticker-ownwindow.pngbin0 -> 7496 bytes
-rw-r--r--doc/knewsticker/newarticle-icon.pngbin0 -> 641 bytes
-rw-r--r--doc/knewsticker/newssite-icon.pngbin0 -> 293 bytes
-rw-r--r--doc/knewsticker/oldarticle-icon.pngbin0 -> 494 bytes
-rw-r--r--doc/knewsticker/preferences-icon.pngbin0 -> 646 bytes
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ
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
Binary files differ