doc/knewsticker/index.docbook

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
   3 <!ENTITY kappname "&knewsticker;">
   4 <!ENTITY package "kdenetwork">
   5 <!ENTITY % addindex "IGNORE">
   6 <!ENTITY % English "INCLUDE">
   7 <!ENTITY RSS "<acronym>RSS</acronym>">
   8 ]>
   9
  10 <book lang="&language;">
  11
  12 <bookinfo>
  13 <title>The &knewsticker; Handbook</title>
  14
  15 <authorgroup>
  16         <author>&Frerich.Raabe; &Frerich.Raabe.mail;</author>
  17         <othercredit role="reviewer">&Jonathan.Singer; &Jonathan.Singer.mail;</othercredit>
  18         <!-- TRANS:ROLES_OF_TRANSLATORS -->
  19 </authorgroup>
  20
  21 <copyright>
  22         <year>2001, 2002, 2003</year>
  23         <holder>&Frerich.Raabe;</holder>
  24 </copyright>
  25
  26 <legalnotice>&FDLNotice;</legalnotice>
  27
  28 <date>2003-10-14</date>
  29 <releaseinfo>2.00.00</releaseinfo>
  30
  31 <abstract>
  32         <para>&knewsticker; is a news ticker applet for the &kde; panel (also
  33         known as &kicker;).</para>
  34 </abstract>
  35
  36 <keywordset>
  37         <keyword>KDE</keyword>
  38         <keyword>KNewsTicker</keyword>
  39         <keyword>kdenetwork</keyword>
  40         <keyword>news ticker</keyword>
  41         <keyword>applet</keyword>
  42 </keywordset>
  43 </bookinfo>
  44
  45 <chapter id="introduction">
  46 <title>Introduction</title>
  47
  48 <para>&knewsticker; is an applet for the &kde; panel (also known as &kicker;)
  49 which provides an easy and convenient way to access the news as reported by
  50 many news sites (such as <ulink url="http://slashdot.org">Slashdot</ulink>,
  51 <ulink url="http://lwn.net">&Linux; Weekly News</ulink> or
  52 <ulink url="http://freshmeat.net">Freshmeat</ulink>).</para>
  53
  54 <para>To achieve this, &knewsticker; requires the news sites to provide a
  55 special &RSS; file, which contains the headlines as well as
  56 pointers to the corresponding full articles. Such files are very common these
  57 days, and &knewsticker; already comes with a selection of good news sources
  58 which provide such files.</para>
  59
  60 <sect1 id="rssfiles">
  61 <title>Brief Info On &RSS; Files</title>
  62
  63 <para>&RSS; files are becoming more and more popular these
  64 days, and this applet is not the first application which takes advantage of
  65 them. But what are &RSS; files? This section tries to give
  66 a brief answer to this question, as well as pointers to other sources for
  67 further reference.</para>
  68
  69 <para>The short answer: &RSS; is an
  70 <acronym>&XML;-based</acronym> format for syndicating web content.</para>
  71
  72 <para>&RSS; is often used as an acronym for <quote>Rich Site
  73 Summary</quote> &ndash; that's not a common definition but it gives an idea on what
  74 the creators of &RSS; had in mind. There is no consensus on
  75 what &RSS; stands for, so it's actually not an acronym, it's a
  76 name.</para>
  77
  78 <para>&RSS; originated in 1999 and was invented by
  79 <ulink url="http://www.netscape.com">NetScape</ulink> as a syndication format
  80 for their <ulink url="http://my.netscape.com">my.netscape.com</ulink> website;
  81 this very first &RSS; release was version 0.9. A few months
  82 after that, &Netscape; introduced &RSS; version 0.91, which
  83 incorporated many features of the <quote>&lt;scriptingNews&gt;</quote>
  84 format.</para>
  85
  86 <para>The basic concept of all &RSS; files is to provide a
  87 clean, simple and portable way to distribute web content, in particular news:
  88 the news sites provide an &RSS; file which basically contains
  89 a set of records, and each record consists of a headline and a
  90 &URL; which points to the complete article. The
  91 &RSS; file also contains other general information about the
  92 particular news site, such as its name and the homepage, which is evaluated
  93 by &knewsticker;.</para>
  94
  95 <para>Nowadays there are a few additional, more sophisticated versions of the
  96 &RSS; format
  97 (<ulink url="http://backend.userland.com/rss091">0.91</ulink>,
  98 <ulink url="http://backend.userland.com/rss092">0.92</ulink>,
  99 <ulink url="http://backend.userland.com/rss093">0.93</ulink>,
 100 <ulink url="http://web.resource.org/rss/1.0/">1.0</ulink> and the current
 101 format version
 102 <ulink url="http://backend.userland.com/rss">2.0</ulink>) but the first two
 103 versions still make up about 85% of the files provided on the web. Nevertheless,
 104 all versions up to 2.0 can be processed with &knewsticker;!</para>
 105
 106 <para>Of course, this is only a short and highly incomplete attempt at
 107 explaining the basic ideas behind &RSS; files. If you're
 108 interested in this topic, you might want to visit any of the following links
 109 which point to further and more complete sources on this:</para>
 110
 111 <variablelist>
 112 <varlistentry>
 113         <term><ulink url="http://www.webreference.com/authoring/languages/xml/rss/intro/">http://www.webreference.com/authoring/languages/xml/rss/intro/</ulink></term>
 114         <listitem><para>A very pragmatic introduction to the &RSS;
 115         format, with concrete examples and guidelines. Together with the
 116         authoritative specifications, this makes a good guide for people
 117         who are thinking
 118         about providing an &RSS; newsfeed on their home
 119         page.</para></listitem>
 120 </varlistentry>
 121 <varlistentry>
 122         <term><ulink url="http://www.oreillynet.com/rss/">http://www.oreillynet.com/rss/</ulink></term>
 123         <listitem><para>The &RSS; page from O'Reilly features a
 124         lot of general articles about employing and using &RSS; files,
 125         up to date news about the &RSS; development community as well
 126         as vital information for web developers who are considering taking advantage of
 127         &RSS;.</para></listitem>
 128 </varlistentry>
 129 <varlistentry>
 130         <term><ulink url="http://blogspace.com/rss/">http://blogspace.com/rss/</ulink></term>
 131         <listitem><para>This page is another excellent source of news about the
 132         &RSS; development, which is especially interesting to
 133         developers working with &RSS;-based technology.</para></listitem>
 134 </varlistentry>
 135 <varlistentry>
 136         <term><ulink url="http://www.w3.org/RDF/">http://www.w3.org/RDF/</ulink></term>
 137         <listitem><para><emphasis>The</emphasis> authoritative source about
 138         <acronym>RDF</acronym>, an &XML;-based language from which
 139         modern &RSS; versions are derived, published by the
 140         <ulink url="http://www.w3.org">World Wide Web Consortium</ulink>. It features
 141         a comprehensive list of links to other sites on the topic as well as a timeline
 142         of the <acronym>RDF</acronym> development, an overview over the architecture, an
 143         archive with articles about <acronym>RDF</acronym> as well as a carefully
 144         assembled list of tools for developers who intend to work with
 145         <acronym>RDF</acronym>.</para></listitem>
 146 </varlistentry>
 147 </variablelist>
 148
 149 <para>Developers will also want to check the authoritative specifications for
 150 the various &RSS; versions:</para>
 151
 152 <orderedlist>
 153 <title>&RSS; Specifications</title>
 154 <listitem><para>
 155         Version 0.90: <ulink url="http://www.purplepages.ie/rss/netscape/rss0.90.html">http://www.purplepages.ie/rss/netscape/rss0.90.html</ulink>
 156 </para></listitem>
 157 <listitem><para>
 158         Version 0.91: <ulink url="http://backend.userland.com/rss091">http://backend.userland.com/rss091</ulink>
 159 </para></listitem>
 160 <listitem><para>
 161         Version 0.92: <ulink url="http://backend.userland.com/rss092">http://backend.userland.com/rss092</ulink>
 162 </para></listitem>
 163 <listitem><para>
 164         Version 0.93: <ulink url="http://backend.userland.com/rss093">http://backend.userland.com/rss093</ulink>
 165 </para></listitem>
 166 <listitem><para>
 167         Version 1.0: <ulink url="http://web.resource.org/rss/1.0/">http://web.resource.org/rss/1.0/</ulink>
 168 </para></listitem>
 169 <listitem><para>
 170         Version 2.0: <ulink url="http://backend.userland.com/rss">http://backend.userland.com/rss</ulink>
 171 </para></listitem>
 172 </orderedlist>
 173
 174 <para>If you find any other sites or documents on this topic, and think they are
 175 worth being mentioned here, don't hesitate to send them to &Frerich.Raabe;
 176 &Frerich.Raabe.mail; so that they can be included in this document and
 177 help everybody.</para>
 178
 179 <para>Thank you very much!</para>
 180 </sect1>
 181 </chapter>
 182
 183 <chapter id="starting-knewsticker">
 184 <title>Starting &knewsticker;</title>
 185
 186 <screenshot>
 187         <screeninfo>Here is a screenshot of &knewsticker; in &kde;'s
 188         panel.</screeninfo>
 189         <mediaobject>
 190                 <imageobject><imagedata fileref="knewsticker-kicker.png" format="PNG"/></imageobject>
 191                 <textobject>
 192                         <phrase>Here is a screenshot of &knewsticker; in &kde;'s
 193                         panel.</phrase>
 194                 </textobject>
 195         </mediaobject>
 196 </screenshot>
 197
 198 <para>
 199 &knewsticker; is started like every other &kicker; applet. You just have to add
 200 it to the panel (or any child panel of the main one). To do so, just right-click
 201 on the &kde; panel and choose <guimenuitem>Add Applet to Panel...</guimenuitem>
 202 and <guilabel>News Ticker</guilabel> in the dialog.</para>
 203
 204 <screenshot>
 205         <screeninfo>Here is a screenshot of &knewsticker; in its own child
 206         panel.</screeninfo>
 207         <mediaobject>
 208                 <imageobject><imagedata fileref="knewsticker-childpanel.png" format="PNG"/></imageobject>
 209                 <textobject>
 210                         <phrase>Here is a screenshot of &knewsticker; in its own child
 211                         panel.</phrase>
 212                 </textobject>
 213         </mediaobject>
 214 </screenshot>
 215
 216 <para>Another good way to use &knewsticker; is to put it into its own child
 217 panel. Just add a new child panel by choosing <menuchoice>
 218 <guimenu>New Panel</guimenu><guimenuitem>Panel</guimenuitem>
 219 </menuchoice> from the panel menu;. Now you can simply right-click on the child
 220 panel and select &knewsticker; as described above.</para>
 221
 222 <screenshot>
 223         <screeninfo>Here is a screenshot of &knewsticker; in its own
 224         window.</screeninfo>
 225         <mediaobject>
 226                 <imageobject><imagedata fileref="knewsticker-ownwindow.png" format="PNG"/></imageobject>
 227                 <textobject>
 228                         <phrase>Here is a screenshot of &knewsticker; in its own
 229                         window.</phrase>
 230                 </textobject>
 231         </mediaobject>
 232 </screenshot>
 233
 234 <para>A third, popular, way to run &knewsticker; is by selecting <menuchoice>
 235 <guimenu>Internet</guimenu><guisubmenu>More Applications</guisubmenu><guimenuitem>&knewsticker; (News
 236 Ticker)</guimenuitem></menuchoice> from the <guilabel>K</guilabel> menu. This
 237 will start &knewsticker; and make it run in its own window which you can then
 238 resize and move around as you wish.</para>
 239 </chapter>
 240
 241 <chapter id="configuration">
 242 <title>Configuring &knewsticker;</title>
 243
 244 <para>You can access &knewsticker;'s configuration dialog by right-clicking
 245 onto the scroll text, or by clicking on the button with the arrow on it and
 246 choosing the entry labelled <guimenuitem><inlinemediaobject><imageobject>
 247 <imagedata fileref="preferences-icon.png" format="PNG"/></imageobject>
 248 </inlinemediaobject> Preferences</guimenuitem> in the menu.</para>
 249
 250 <sect1 id="config-general">
 251 <title>General Options</title>
 252
 253 <screenshot>
 254         <screeninfo>This is what the <guilabel>General</guilabel> tab of the
 255         preferences dialog looks like.</screeninfo>
 256         <mediaobject>
 257                 <imageobject><imagedata fileref="kcmnewsticker-general.png" format="PNG"/></imageobject>
 258                 <textobject>
 259                         <phrase>This is what the <guilabel>General</guilabel> tab of the
 260                         preferences dialog looks like.</phrase>
 261                 </textobject>
 262         </mediaobject>
 263 </screenshot>
 264
 265 <para>Here you can define how fast the text should be scrolled around, what it
 266 should look like as well as other options for the applet. Here is a brief info
 267 on what each of the switches and buttons on this tab does:</para>
 268
 269 <variablelist>
 270 <varlistentry>
 271         <term><guilabel>Mousewheel sensitivity:</guilabel></term>
 272         <listitem>
 273                 <para>This slider allows you to define how fast/slow the text should be
 274                 scrolled when using the mousewheel.</para>
 275         </listitem>
 276 </varlistentry>
 277 <varlistentry>
 278         <term><guilabel>News query interval</guilabel></term>
 279         <listitem>
 280                 <para>Here you can define in what intervals &knewsticker; queries the
 281                 configured news sources for new headlines. This depends generally on
 282                 how fast you'd like to hear about news and how much load you want to
 283                 put on the network:</para>
 284                 <itemizedlist>
 285                         <listitem>
 286                                 <para>A lower value (lower than 15 minutes) enables you to be
 287                                 notified about news very quickly if you want or need to. Please
 288                                 note, that it increases the network traffic significantly,
 289                                 though. Therefore, such low values shouldn't be used if you
 290                                 query popular news sites (such as
 291                                 <ulink url="http://slashdot.org">Slashdot</ulink> or
 292                                 <ulink url="http://freshmeat.net">Freshmeat</ulink>) as they
 293                                 have generally already enough work with processing the incoming
 294                                 queries.</para>
 295                         </listitem>
 296                         <listitem>
 297                                 <para>A higher value (higher than 45 minutes) won't make you
 298                                 hear about news that quick. For non-time-critical applications,
 299                                 it should be suitable, though. The positive aspect of longer
 300                                 intervals is that only very little load is put on the network;
 301                                 this saves resources and nerves, for you and the system
 302                                 administrators of the news sites you query.</para>
 303                         </listitem>
 304                 </itemizedlist>
 305                 <tip><para>The default value (30 minutes) should be appropriate and
 306                 reasonable in most cases.</para></tip>
 307         </listitem>
 308 </varlistentry>
 309 <varlistentry>
 310         <term><guilabel>Use custom names for news sites</guilabel></term>
 311         <listitem>
 312                 <para>Check this box to make the news ticker use the names you
 313                 specified in the list of news sources (available on the tab
 314                 labeled <guilabel>News sources</guilabel>) instead of the ones
 315                 the news sites themselves report. This can be handy for news sites
 316                 which report a very long or useless name.</para>
 317         </listitem>
 318 </varlistentry>
 319 </variablelist>
 320 </sect1>
 321
 322 <sect1 id="config-newssources">
 323 <title>Configuration of the news sources</title>
 324
 325 <screenshot>
 326         <screeninfo>This is what the <guilabel>News Sources</guilabel> tab of the
 327         preferences dialog looks like.</screeninfo>
 328         <mediaobject>
 329                 <imageobject><imagedata fileref="kcmnewsticker-newssources.png" format="PNG"/></imageobject>
 330                 <textobject>
 331                         <phrase>This is what the <guilabel>News Sources</guilabel> tab of
 332                         the preferences dialog looks like.</phrase>
 333                 </textobject>
 334         </mediaobject>
 335 </screenshot>
 336
 337 <para>On this tab you can manage and maintain the list of news sites
 338 &knewsticker; queries for news. Click on any entry with the right mouse button
 339 to open a context menu which lets you remove the current entry, or add a new
 340 entry. At the bottom of the page you can also find three buttons which have
 341 the same effect.</para>
 342
 343 <sect2>
 344 <title>Adding a news site</title>
 345 <para>There are four ways to <emphasis>add</emphasis> a new news site to the
 346 list:</para>
 347 <itemizedlist>
 348         <listitem>
 349                 <para>You can click on the button at the bottom labeled
 350                 <guilabel>Add...</guilabel>.</para>
 351         </listitem>
 352         <listitem>
 353                 <para>You can click with the right mouse button on the table and choose
 354                 <guimenuitem>Add news source</guimenuitem>.</para>
 355         </listitem>
 356         <listitem>
 357                 <para>You can drag any &RSS; file from another
 358                 application (such as &konqueror;) onto the table. This adds a new entry
 359                 to the list, sets the name to <quote>Unknown</quote> and sets the
 360                 maximum number of articles to 10.</para>
 361         </listitem>
 362         <listitem>
 363                 <para>And finally, you can just click on any &RSS;
 364                 file in the &konqueror; filemanager to have it added to the list
 365                 immediately.</para>
 366         </listitem>
 367 </itemizedlist>
 368 <para>Either way will cause the <link linkend="config-news-site-dialog">News site
 369 dialog</link> to show up, presenting you with a form to enter the properties of
 370 the news site to add.</para>
 371 </sect2>
 372
 373 <sect2>
 374 <title>Modifying an existing news site</title>
 375 <para>There are two ways to adjust the properties of an existing news
 376 site:</para>
 377 <itemizedlist>
 378         <listitem>
 379                 <para>You can click on the button at the bottom labeled
 380                 <guilabel>Modify...</guilabel>.</para>
 381         </listitem>
 382         <listitem>
 383                 <para>You can right-click with the right mouse button on the news site
 384                 you'd like to edit and choose <guimenuitem>Modify '...'</guimenuitem>
 385                 from the menu.</para>
 386         </listitem>
 387 </itemizedlist>
 388 <para>No matter which way you chose, it will cause the
 389 <link linkend="config-news-site-dialog">News site dialog</link> to pop up,
 390 showing the properties of the selected news site.</para>
 391 </sect2>
 392
 393 <sect2>
 394 <title>Removing a news site</title>
 395 <para>Of course, you want to <emphasis>remove</emphasis> a news source from
 396 the list sometimes. To do this, you can either</para>
 397 <itemizedlist>
 398         <listitem>
 399                 <para>click on the button at the bottom labeled
 400                 <guilabel>Remove</guilabel>, or</para>
 401         </listitem>
 402         <listitem>
 403                 <para>right-click with the right mouse button on the news site
 404                 you'd like to edit and choose <guimenuitem>Remove '...'</guimenuitem>
 405                 from the menu.</para>
 406         </listitem>
 407 </itemizedlist>
 408 <para>In both cases, a confirmation box will pop up and make sure you didn't
 409 select the wrong entry.</para>
 410 <tip><para>You can also remove multiple news sites at once by holding &Ctrl;
 411 while clicking on the entries you wouldd like to remove, or by clicking the
 412 <mousebutton>left</mousebutton> mousebutton and dragging the mouse over all
 413 the entries you'd like to select.</para></tip>
 414 </sect2>
 415
 416 <sect2 id="config-news-site-dialog">
 417 <title>The news site dialog</title>
 418
 419 <screenshot>
 420         <screeninfo>This is what the dialog for adding and editing news sites looks
 421         like.</screeninfo>
 422         <mediaobject>
 423                 <imageobject><imagedata fileref="kcmnewsticker-newssitedialog.png" format="PNG"/></imageobject>
 424                 <textobject>
 425                         <phrase>This is what the dialog for adding and editing news sites
 426                         looks like.</phrase>
 427                 </textobject>
 428         </mediaobject>
 429 </screenshot>
 430
 431 <para>When adding or modifying a news site, the news site dialog (shown above)
 432 pops up and provides input facilities to edit the various properties of a news
 433 site:</para>
 434
 435 <variablelist>
 436 <varlistentry>
 437         <term><guilabel>Name:</guilabel></term>
 438         <listitem>
 439                 <para>This is the name of the news source.</para>
 440                 <note><para>This text will only be used if <guilabel>Use custom names
 441                 for news sites</guilabel> on the tab labeled
 442                 <link linkend="config-general">General</link> is
 443                 activated.</para></note>
 444         </listitem>
 445 </varlistentry>
 446 <varlistentry>
 447         <term><guilabel>Source file:</guilabel></term>
 448         <listitem>
 449                 <para>Here you can set the &URL; which references
 450                 the &RSS; file of this news site; this can either
 451                 be a local file, or a file saved on a remote server. You can also
 452                 click on the button at the right to open a convenient file-selection
 453                 dialog and browse to the file you would like to use, instead of typing
 454                 the &URL; by hand.</para>
 455         </listitem>
 456 </varlistentry>
 457 <varlistentry>
 458         <term><guilabel>The file is a program</guilabel></term>
 459         <listitem>
 460                 <para>If this file is checked, &knewsticker; will not assume that the
 461                 &URL; (which was specified in the <guilabel>Source
 462                 file</guilabel> field) references an &RSS; file, but
 463                 rather that the &URL; refers a program (usually a
 464                 script). When querying this news site, &knewsticker; will execute the
 465                 program and treat whatever the program prints to stdout as
 466                 &RSS; markup. This is very convenient for conversion
 467                 scripts which download an &HTML; file and process it,
 468                 producing &RSS; markup which is suitable for use with
 469                 &knewsticker;.</para>
 470                 <tip><para>You can find some scripts which &eg; download stock data in
 471                 the kdeaddons module, in the
 472                 <filename class="directory">knewsticker-scripts</filename>
 473                 directory.</para></tip>
 474         </listitem>
 475 </varlistentry>
 476 <varlistentry>
 477         <term><guilabel>Category:</guilabel></term>
 478         <listitem>
 479                 <para>Here you can specify into which category the news site belongs.
 480                 Arranging the news sites into categories makes it much easier to
 481                 maintain large lists of news sites.</para>
 482         </listitem>
 483 </varlistentry>
 484 <varlistentry>
 485         <term><guilabel>Max. articles:</guilabel></term>
 486         <listitem>
 487                 <para>This option lets you define how many articles &knewsticker; will
 488                 cache for this news site; the value will never be exceeded.</para>
 489                 <para>This is particularly handy for news sites which provide only
 490                 three news items at once, but you'd like to see the last ten items (for
 491                 instance); &knewsticker; will always download the three items and merge
 492                 them into its list, caching the last seven items.</para>
 493         </listitem>
 494 </varlistentry>
 495 <varlistentry>
 496         <term><guilabel>Icon:</guilabel></term>
 497         <listitem>
 498                 <para>Here you can specify a &URL; to an image file
 499                 (preferably 16x16 pixels in size) which should be used for this news
 500                 site. Icons make it much easier to distinguish multiple news sites, and
 501                 see which news site a headline appeared on as it scrolls by in
 502                 &knewsticker;.</para>
 503         </listitem>
 504 </varlistentry>
 505 </variablelist>
 506
 507 <para>At the button you will find the usual buttons. One of them deserves an
 508 extra note: clicking on the <guilabel>Suggest</guilabel> button will make
 509 &knewsticker; try to guess suitable values for most of the fields if you
 510 specify a &URL; to a valid source file.</para>
 511
 512 <para>This means that you can usually just paste a &URL; to
 513 an &RSS; file in the input field labeled <guilabel>Source
 514 file</guilabel>, press the <guilabel>Suggest</guilabel> button and then modify
 515 the suggested values as needed.</para>
 516 </sect2>
 517 </sect1>
 518
 519 <sect1 id="config-filters">
 520 <title>Filters</title>
 521
 522 <screenshot>
 523         <screeninfo>This is what the <guilabel>Filters</guilabel> tab of the
 524         preferences dialog looks like.</screeninfo>
 525         <mediaobject>
 526                 <imageobject><imagedata fileref="kcmnewsticker-filters.png" format="PNG"/></imageobject>
 527                 <textobject>
 528                         <phrase>This is what the <guilabel>Filters</guilabel> tab of
 529                         the preferences dialog looks like.</phrase>
 530                 </textobject>
 531         </mediaobject>
 532 </screenshot>
 533
 534 <para>This tab allows you to define various filters which should be applied
 535 before showing the headlines in the scroll text.</para>
 536
 537 <note><para>These filters only affect the headlines which are shown in the
 538 scrolltext; the menu will always show all of the headlines.</para></note>
 539 <para>The major part of the tab is occupied by a table which lists the
 540 currently configured filters. Each filter has a small checkable box - checking
 541 that box enables the filter, unchecking it temporarily disables it without
 542 removing it from the list.</para>
 543
 544 <para>By default there are no filters, so chances are that the table is
 545 completely empty for you. Of course, this dialog provides you with ways
 546 to add new filters, and manage them in general:</para>
 547
 548 <itemizedlist>
 549 <listitem>
 550         <para>To <emphasis>add</emphasis> a filter, simply enter the filter
 551         properties (see <link linkend="filter-components">Filter
 552         Components</link> for a detailed description of the various filter
 553         properties) using the input fields in the box labeled <guilabel>Filter
 554         properties</guilabel> and then press the button labeled
 555         <guilabel>Add</guilabel>.</para>
 556 </listitem>
 557 <listitem>
 558         <para>To <emphasis>modify</emphasis> an existing filter, select the
 559         filter you would like to edit in the table by left-clicking on it and
 560         then change its properties in the box at the bottom.</para>
 561 </listitem>
 562 <listitem>
 563         <para>To <emphasis>remove</emphasis> a filter, select it in the table
 564         and then press the button labeled <guilabel>Remove</guilabel>.</para>
 565 </listitem>
 566 </itemizedlist>
 567
 568 <sect2 id="filter-components">
 569 <title>Filter Components</title>
 570
 571 <para>Each filter consists of four components:</para>
 572
 573 <orderedlist>
 574 <title>Filter Components</title>
 575 <listitem>
 576         <para>Action &ndash; this can be either <guilabel>Show</guilabel> or
 577         <guilabel>Hide</guilabel> and defines what should happen to a headline
 578         in case this filter matches.</para>
 579 </listitem>
 580 <listitem>
 581         <para>News sources &ndash; here you can define whether the filter affects only
 582         single news sources, or whether this filter should be applied to the
 583         headlines of all news sources.</para>
 584 </listitem>
 585 <listitem>
 586         <para>Condition &ndash; this is a verb which defines, together with the
 587         Expression, whether a filter matches. A condition can be &eg;
 588         <guilabel>contains</guilabel>, <guilabel>doesn't equal</guilabel> or
 589         <guilabel>matches</guilabel>. See below for a more detailed
 590         description.</para>
 591 </listitem>
 592 <listitem>
 593         <para>Expression - this is a user-defined string which forms the body
 594         of the filter, together with the Condition. See below for a more detailed
 595         description of this component.</para>
 596 </listitem>
 597 </orderedlist>
 598
 599 <para>All these components can be configured using the facilities in the frame
 600 labeled <guilabel>Filter properties</guilabel>. The possible states of the
 601 Condition component deserve a special explanation:</para>
 602
 603 <itemizedlist>
 604 <listitem>
 605         <para><guilabel>contains</guilabel>, <guilabel>doesn't contain</guilabel>:
 606         this filter matches if the headline contains / doesn't contain the
 607         specified expression.</para>
 608         <note><para>The expression isn't treated case-sensitively, so the expressions
 609         <quote>KDE</quote>, <quote>kDE</quote> or <quote>kde</quote> will all match
 610         headlines which contain <quote>KDE</quote>.</para></note>
 611 </listitem>
 612 <listitem>
 613         <para><guilabel>equals</guilabel>, <guilabel>doesn't equal</guilabel>:
 614         this filter matches if the headline equals / doesn't equal the
 615         specified expression.</para>
 616         <note><para>The expression is treated case-sensitively, so of the expressions
 617         <quote>&Linux;</quote>, <quote>linux</quote> or <quote>LINUX</quote>, only the
 618         first will match <quote>&Linux;</quote>.</para></note>
 619 </listitem>
 620 <listitem>
 621         <para><guilabel>matches</guilabel>: using this condition will make
 622         &knewsticker; treat the given expression as a <quote>regular
 623         expression</quote>. For further information on regular expressions you
 624         might want to read
 625         <ulink url="http://www.evolt.org/article/rating/20/22700/">this
 626         article</ulink> which was published at
 627         <ulink url="http://www.evolt.org">www.evolt.org</ulink>.</para>
 628 </listitem>
 629 </itemizedlist>
 630 </sect2>
 631 </sect1>
 632
 633 <sect1 id="config-scroller">
 634 <title>Scroller Preferences</title>
 635
 636 <screenshot>
 637         <screeninfo>This is what the <guilabel>Scroller Preferences</guilabel> tab
 638         of the preferences dialog looks like.</screeninfo>
 639         <mediaobject>
 640                 <imageobject><imagedata fileref="kcmnewsticker-scrollerprefs.png" format="PNG"/></imageobject>
 641                 <textobject>
 642                         <phrase>This is what the <guilabel>Scroller Preferences</guilabel>
 643                         tab of the preferences dialog looks like.</phrase>
 644                 </textobject>
 645         </mediaobject>
 646 </screenshot>
 647
 648 <para>This tab lets you define various options which affect &knewsticker;'s
 649 scroll text:</para>
 650
 651 <variablelist>
 652 <varlistentry>
 653         <term><guilabel>Scrolling speed</guilabel></term>
 654         <listitem>
 655                 <para>This slider lets you define how fast the scrolltext should be
 656                 scrolling. If you have rather little space on your taskbar (and
 657                 therefore a rather small news ticker), you should probably set this
 658                 to a lower value so that you have a chance to read the headlines.
 659                 For wider news tickers (and better eyes), a faster text is probably
 660                 appropriate so that you have to wait for the next headline only as
 661                 little as possible.</para>
 662         </listitem>
 663 </varlistentry>
 664 <varlistentry>
 665         <term><guilabel>Direction of scrolling</guilabel></term>
 666         <listitem>
 667                 <para>These options allow you to define in what direction the text
 668                 should be scrolled, &eg; to the left or to the right, upwards or
 669                 downwards. You can also rotate the text by 90 or 270 degrees here,
 670                 which is not exactly readable but it makes sense for vertically
 671                 aligned panels.</para>
 672         </listitem>
 673 </varlistentry>
 674 <varlistentry>
 675         <term><guilabel>Scrolltext font</guilabel></term>
 676         <listitem>
 677                 <para>Click on the button at the right labeled <guilabel>Choose
 678                 Font...</guilabel> to choose the font which will be used for the
 679                 scrolling text.</para>
 680                 <tip><para>Certain fonts are harder to read than others, especially
 681                 when they are used for a scrolltext, so you should probably choose a font
 682                 which can even easily be read if it's moving.</para></tip>
 683         </listitem>
 684 </varlistentry>
 685 <varlistentry>
 686         <term><guilabel>Foreground color</guilabel></term>
 687         <listitem>
 688                 <para>Click this button open a convenient color-selection dialog which
 689                 lets you choose the color which will be used for the foreground of the
 690                 scrolling text (&ie; the color of the text itself).</para>
 691         </listitem>
 692 </varlistentry>
 693 <varlistentry>
 694         <term><guilabel>Background color</guilabel></term>
 695         <listitem>
 696                 <para>Click this button to open a convenient color-selection dialog
 697                 which lets you choose the color which will be used for the background
 698                 of the scrolling text.</para>
 699         </listitem>
 700 </varlistentry>
 701 <varlistentry>
 702         <term><guilabel>Highlighted color</guilabel></term>
 703         <listitem>
 704                 <para>Click this button to open a convenient color-selection dialog
 705                 which lets you choose the color which will be used for the color of
 706                 the headlines when they are highlighted (when you move the mouse over
 707                 them).</para>
 708         </listitem>
 709 </varlistentry>
 710 <varlistentry>
 711         <term><guilabel>Scroll the most recent headlines only</guilabel></term>
 712         <listitem>
 713                 <para>Check this button to make the scrolltext show just the most
 714                 recent headline for each news site, instead of showing every
 715                 headline available from every news site.</para>
 716         </listitem>
 717 </varlistentry>
 718 <varlistentry>
 719         <term><guilabel>Show icons</guilabel></term>
 720         <listitem>
 721                 <para>Checking this box will make &knewsticker; show an icon (if
 722                 available) in front of each headline which is scrolled along; this
 723                 makes determining which news site provided each headline much
 724                 easier.</para>
 725         </listitem>
 726 </varlistentry>
 727 <varlistentry>
 728         <term><guilabel>Temporarily slowed scrolling</guilabel></term>
 729         <listitem>
 730                 <para>Check this box to make &knewsticker; slow the scrolling down
 731                 when you move the mouse cursor over the scrolling text. This makes
 732                 clicking on items and dragging away the icons (if enabled) a lot
 733                 easier.</para>
 734         </listitem>
 735 </varlistentry>
 736 <varlistentry>
 737         <term><guilabel>Underline highlighted headline</guilabel></term>
 738         <listitem>
 739                 <para>Check this box to have the currently highlighted headline
 740                 (&ie; the headline which is currently under the mouse cursor)
 741                 underlined.</para>
 742         </listitem>
 743 </varlistentry>
 744 </variablelist>
 745 </sect1>
 746 </chapter>
 747
 748 <chapter id="using-knewsticker">
 749 <title>Using &knewsticker;</title>
 750
 751 <para>Using &knewsticker; is fairly straightforward and should give you no
 752 big problems, assuming that you have already
 753 <link linkend="configuration">configured it</link>. No matter
 754 whether you are running &knewsticker; in the main panel, in its own child
 755 panel or in its own window, it appears as an area with a scrolling text and
 756 a button with a small arrow next to it.</para>
 757
 758 <sect1 id="applet-descr">
 759 <title>The Main Interface</title>
 760
 761 <para>The area (it is white by default, but you can change the background
 762 color easily using the preferences dialog) with the scrolling text in it is
 763 called the <quote>news scroller</quote>. It keeps scrolling the downloaded
 764 headlines (or just the most recent headlines) continuously and provides easy
 765 access to the articles. If you see an interesting article, just click on it
 766 to open the &konqueror; web browser, showing the full article which belongs to
 767 the headline you clicked on. If you feel that a possibly interesting headline
 768 just scrolled out of view, you have some ways to influence the
 769 scrolling:</para>
 770
 771 <itemizedlist>
 772         <listitem>
 773                 <para>You can click on the news scroller with the
 774                 <mousebutton>left</mousebutton> mouse button and move the mouse around
 775                 (while holding the <mousebutton>left</mousebutton> mouse button pressed
 776                 down). The news scroller will continue scrolling as usual if you release
 777                 the left mouse button again.</para>
 778         </listitem>
 779         <listitem>
 780                 <para>If you own a so-called <quote>wheel mouse</quote>, you can use
 781                 the wheel on your mouse to scroll the headlines back and forth.</para>
 782         </listitem>
 783 </itemizedlist>
 784
 785 <para>There's also a very powerful <link linkend="contextmenu-descr">context
 786 menu</link>, which you can access either by clicking on the news scroller with
 787 the <mousebutton>right</mousebutton> mouse button, or by clicking on the
 788 arrow button with the <mousebutton>left</mousebutton> button. This context menu
 789 is the most interesting part of the applet, as it contains about all the
 790 functionality.</para>
 791 </sect1>
 792
 793 <sect1 id="contextmenu-descr">
 794 <title>The Context Menu</title>
 795
 796 <screenshot>
 797         <screeninfo>This is what the context menu of &knewsticker; looks like, when
 798         using just the default news sites.</screeninfo>
 799         <mediaobject>
 800                 <imageobject><imagedata fileref="contextmenu.png" format="PNG"/></imageobject>
 801                 <textobject>
 802                         <phrase>This is what the context menu of &knewsticker; looks like,
 803                         when using just the default news sites.</phrase>
 804                 </textobject>
 805         </mediaobject>
 806 </screenshot>
 807
 808 <para>The context menu is basically split into two functional parts:</para>
 809
 810 <para>The upper part shows a list of entries, each entry having a small icon like
 811 this <inlinemediaobject><imageobject>
 812 <imagedata fileref="newssite-icon.png" format="PNG"/></imageobject>
 813 </inlinemediaobject> next to it. This list represents
 814 the list of currently configured news sites. You can click on any of the news
 815 sources to open another menu which contains a listing of headlines which are
 816 available for that particular news site as well as an entry labeled <guilabel>
 817 <inlinemediaobject><imageobject><imagedata fileref="checknews-icon.png"
 818 format="PNG"/></imageobject></inlinemediaobject> Check news</guilabel> to
 819 refresh the headline list for this news site. Each of the headlines has an
 820 <inlinemediaobject><imageobject>
 821 <imagedata fileref="oldarticle-icon.png" format="PNG"/></imageobject>
 822 </inlinemediaobject> icon next to it indicating that that you
 823 have read that article already or the <inlinemediaobject><imageobject>
 824 <imagedata fileref="newarticle-icon.png" format="PNG"/></imageobject>
 825 </inlinemediaobject> if it is still
 826 unread.</para>
 827
 828 <para>The lower part currently shows five entries (explained from top to
 829 bottom):</para>
 830
 831 <variablelist>
 832 <varlistentry>
 833         <term><guilabel><inlinemediaobject><imageobject><imagedata fileref="checknews-icon.png" format="PNG"/></imageobject></inlinemediaobject> Check news</guilabel></term>
 834         <listitem>
 835                 <para>This entry has a little <inlinemediaobject><imageobject>
 836                 <imagedata fileref="checknews-icon.png" format="PNG"/></imageobject>
 837                 </inlinemediaobject> next to it. If you want to force &knewsticker;
 838                 to check the configured news sites for new articles, you can click
 839                 here.</para>
 840                 <note><para>This does not reset the internal timer which queries the
 841                 news sites for new headlines automatically in certain
 842                 intervals.</para></note>
 843         </listitem>
 844 </varlistentry>
 845 <varlistentry>
 846         <term><guilabel>Offline mode</guilabel></term>
 847         <listitem>
 848                 <para>This entry in the context menu has no icon associated with it.
 849                 Click this button to enable a special <quote>offline mode</quote>
 850                 which pauses the internal timer for querying the news sites and
 851                 prevents any automatic download of new headlines. The offline mode
 852                 comes in handy if you have to leave your computer for a while
 853                 during which the system isn't connected to the Internet, as it
 854                 saves you from all the error messages which pop up if any of the
 855                 news sites couldn't be connected.</para>
 856                 <tip><para>You can still force a reload for single news sites as
 857                 well as for all the news sites by selecting the respective
 858                 <guilabel><inlinemediaobject><imageobject><imagedata
 859                 fileref="checknews-icon.png" format="PNG"/></imageobject>
 860                 </inlinemediaobject> Check news</guilabel> entry.</para></tip>
 861         </listitem>
 862 </varlistentry>
 863 <varlistentry>
 864         <term><guilabel><inlinemediaobject><imageobject><imagedata fileref="help-icon.png" format="PNG"/></imageobject></inlinemediaobject> Help</guilabel></term>
 865         <listitem>
 866                 <para>This entry is marked with a small <inlinemediaobject>
 867                 <imageobject><imagedata fileref="help-icon.png" format="PNG"/>
 868                 </imageobject></inlinemediaobject>. Clicking on this entry opens
 869                 the &knewsticker; documentation (which you're reading in this
 870                 moment) which details all the features and abilities of
 871                 &knewsticker;.</para>
 872         </listitem>
 873 </varlistentry>
 874 <varlistentry>
 875         <term><guilabel><inlinemediaobject><imageobject><imagedata fileref="knewsticker-icon.png" format="PNG"/></imageobject></inlinemediaobject> About</guilabel></term>
 876         <listitem>
 877                 <para>This entry is marked with a small <inlinemediaobject>
 878                 <imageobject><imagedata fileref="knewsticker-icon.png" format="PNG"/>
 879                 </imageobject></inlinemediaobject>. Clicking on this entry opens
 880                 a small dialog showing who's to blame for &knewsticker; and credits
 881                 people who contributed significant enhancements for
 882                 it.</para>
 883         </listitem>
 884 </varlistentry>
 885 <varlistentry>
 886         <term><guilabel><inlinemediaobject><imageobject><imagedata fileref="preferences-icon.png" format="PNG"/></imageobject></inlinemediaobject> Preferences</guilabel></term>
 887         <listitem>
 888                 <para>This entry is easily recognizable due to the <inlinemediaobject>
 889                 <imageobject><imagedata fileref="preferences-icon.png" format="PNG"/>
 890                 </imageobject></inlinemediaobject> icon which is next to it. Select
 891                 this entry to open the <link linkend="configuration">preferences
 892                 dialog</link> which lets you customize all of the properties of
 893                 &knewsticker;</para>
 894         </listitem>
 895 </varlistentry>
 896 </variablelist>
 897
 898 </sect1>
 899 </chapter>
 900
 901 <chapter id="faq">
 902 <title>Frequently Asked Questions</title>
 903
 904 &reporting.bugs;
 905
 906 <qandaset id="faqlist">
 907 <qandaentry>
 908         <question>
 909                 <para>Where do I find the &RSS; file for the news
 910                 site XYZ?</para>
 911         </question>
 912         <answer>
 913                 <para>It's possible that the news site you're referring to
 914                 doesn't provide any &RSS; file at all! Here's a short list of
 915                 websites which provide thousands of &RSS; feeds, sorted by
 916                 language and/or topic - for free:</para>
 917
 918                 <itemizedlist>
 919                 <listitem><para>
 920                 <ulink url="http://www.webreference.com/services/news">WebReference.com</ulink>
 921                 </para></listitem>
 922                 <listitem><para>
 923                 <ulink url="http://www.newsisfree.com/syndicate.php">NewsIsFree</ulink>
 924                 </para></listitem>
 925                 <listitem><para>
 926                 <ulink url="http://w.moreover.com/categories/category_list_rss.html">MoreOver</ulink>
 927                 </para></listitem>
 928                 </itemizedlist>
 929
 930                 <para>If you have found any interesting news sites which provide
 931                 such a backend, don't hesitate to send them to &Frerich.Raabe;
 932                 &Frerich.Raabe.mail; so that they can be included in
 933                 future releases. Thank you!</para>
 934         </answer>
 935 </qandaentry>
 936 <qandaentry>
 937         <question>
 938                 <para>How can I make &knewsticker; open articles in another browser
 939                 (&eg; Mozilla)?</para>
 940         </question>
 941         <answer>
 942                 <para>&knewsticker; will use whatever browser you have associated with
 943                 the text/html &MIME; type; the default browser used for viewing
 944                 &HTML; pages is &konqueror;.</para>
 945                 <para>You can find the dialog for changing this association by opening
 946                 the &kde; control center and browsing to <menuchoice><guimenu>KDE
 947                 Components</guimenu> <guisubmenu>File
 948                 Associations</guisubmenu></menuchoice>.</para>
 949         </answer>
 950 </qandaentry>
 951 </qandaset>
 952 </chapter>
 953
 954 <chapter id="credits">
 955 <title>Credits And License</title>
 956
 957 <para>&knewsticker;</para>
 958
 959 <para>Program copyright 2000, 2001, 2002, 2003 &Frerich.Raabe;
 960 &Frerich.Raabe.mail;</para>
 961
 962 <para>Contributors:</para>
 963
 964 <itemizedlist>
 965 <listitem>
 966         <para>Malte Starostik <email>malte.starostik@t-online.de</email></para>
 967 </listitem>
 968 <listitem>
 969         <para>&Wilco.Greven; &Wilco.Greven.mail;</para>
 970 </listitem>
 971 <listitem>
 972         <para>Adriaan de Groot <email>adrig@sci.kun.nl</email></para>
 973 </listitem>
 974 </itemizedlist>
 975
 976 <para>Documentation copyright 2001, 2002, 2003 &Frerich.Raabe;
 977 &Frerich.Raabe.mail;</para>
 978
 979 <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
 980 &underFDL;
 981 &underBSDLicense;
 982 </chapter>
 983
 984 <glossary id="glossary">
 985 <title>Glossary</title>
 986
 987 <para>This chapter is intended to explain the various acronyms which have been
 988 used throughout the &knewsticker; documentation. If you feel any acronyms or
 989 terms are missing here, please don't hesitate to send an email to &Frerich.Raabe;
 990 &Frerich.Raabe.mail; so that they can be added. Thank you!</para>
 991
 992 <glossentry id="gloss-rdf">
 993         <glossterm>RDF</glossterm>
 994         <glossdef>
 995                 <para>Resource Description Framework. A language derived from
 996                 &XML; which describes metadata. Commonly used as a
 997                 backend format for articles and other publications. For more detailed
 998                 information on <acronym>RDF</acronym> files, you might want to go
 999                 directly to the <ulink url="http://www.w3.org/RDF/">official page on
1000                 <acronym>RDF</acronym> files</ulink> at the
1001                 <ulink url="http://www.w3.org">World Wide Web
1002                 Consortium</ulink>.</para>
1003         </glossdef>
1004 </glossentry>
1005 <glossentry id="gloss-rss">
1006         <glossterm>&RSS;</glossterm>
1007         <glossdef>
1008                 <para>The <acronym>RDF</acronym> Site Summary is actually an
1009                 extension to the <acronym>RDF</acronym> language. Quoting the official
1010                 <ulink url="http://www.purl.org/rss/1.0/">&RSS; v1.0
1011                 specification</ulink>:</para>
1012                 <para><quote><acronym>RDF</acronym> Site Summary
1013                 (&RSS;) is a lightweight multipurpose extensible
1014                 metadata description and syndication format. &RSS; is
1015                 an &XML; application, conforms to the
1016                 <acronym>W3C</acronym>'s <acronym>RDF</acronym> specification and is
1017                 extensible via &XML;-namespace and/or
1018                 <acronym>RDF</acronym> based modularization.</quote></para>
1019         </glossdef>
1020 </glossentry>
1021 <glossentry id="gloss-xml">
1022         <glossterm>&XML;</glossterm>
1023         <glossdef>
1024                 <para>The Extensible Markup Language is the <quote>universal format
1025                 for structured documents and data on the Web</quote>. It's a derivative of
1026                 <acronym>SGML</acronym> which fits the needs of the world wide web. You
1027                 might want to check the the
1028                 <ulink url="http://www.w3.org/XML/">Extensible Markup Language</ulink>
1029                 page at the <ulink url="http://www.w3.org">World Wide Web
1030                 Consortium</ulink> for further information.</para>
1031         </glossdef>
1032 </glossentry>
1033 <glossentry id="gloss-w3c">
1034         <glossterm>W3C</glossterm>
1035         <glossdef>
1036                 <para>An abbreviation for <quote>World Wide Web Consortium</quote>.
1037                 Quoting the <ulink url="http://www.w3.org">official homepage</ulink> of
1038                 the <acronym>W3C</acronym>, <quote>the World Wide Web Consortium
1039                 (<acronym>W3C</acronym>) develops interoperable technologies
1040                 (specifications, guidelines, software, and tools) to lead the Web to
1041                 its full potential as a forum for information, commerce, communication,
1042                 and collective understanding</quote></para>
1043         </glossdef>
1044 </glossentry>
1045 <glossentry id="gloss-url">
1046         <glossterm>&URL;</glossterm>
1047         <glossdef>
1048                 <para>&URL; stands for <quote>Uniform Resource Locator</quote>,
1049                 a specially formatted string which can reference resources like images,
1050                 documents and other things on the Internet. Please refer to the
1051                 corresponding <ulink url="http://www.w3.org/Addressing/">webpage</ulink>
1052                 for more detailed information on this topic.</para>
1053         </glossdef>
1054 </glossentry>
1055 <glossentry id="gloss-dcop">
1056         <glossterm>&DCOP;</glossterm>
1057         <glossdef>
1058                 <para>The Desktop COmmunication Protocol is a way for applications
1059                 to communicate to each other. For instance, &knewsticker;'s
1060                 <link linkend="configuration">configuration dialog</link> uses
1061                 &DCOP; to tell the applet itself about the current
1062                 configuration.</para>
1063                 <para>&knewsticker; provides an extensive
1064                 <link linkend="develinfo">&DCOP; interface</link>,
1065                 which makes it possible to control many of &knewsticker;'s functions
1066                 from the commandline.</para>
1067                 <para>For more detailled information on &DCOP;
1068                 you might want to visit
1069                 <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>
1070                 for a complete explanation.</para>
1071         </glossdef>
1072 </glossentry>
1073 </glossary>
1074
1075 <appendix id="develinfo">
1076 <title>Information For Developers And Advanced Users</title>
1077
1078 <para>&knewsticker; features a currently rather extensive, and steadily growing
1079 &DCOP; interface. This is not only used to communicate with
1080 other applications, it makes it possible to control &knewsticker; with a
1081 shell script as well. The more the interface is extended, the more useful it will
1082 become and the more flexible &knewsticker; will be controllable from a
1083 script.</para>
1084
1085 <para>To use these &DCOP; functions you can either use the
1086 <application>dcop</application> commandline program or use the more convenient
1087 <application>KDCOP</application> application. Both provide the same
1088 functionality so it's actually just a matter of taste which program you prefer.
1089 :-)</para>
1090
1091 <para>This chapter assumes that you're using the commandline program
1092 <application>dcop</application>. To access &knewsticker;'s
1093 &DCOP; functions make sure that &knewsticker; is <link
1094 linkend="starting-knewsticker">started</link> and then just enter something like
1095 this at the console:</para>
1096
1097 <screen width="40">
1098 <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>[function]</option></userinput>
1099 </screen>
1100
1101 <note><para>If an error appears that tells you that <filename>dcop</filename>
1102 couldn't be found or executed, please check whether the file
1103 <filename>dcop</filename> exists in
1104 <filename class="directory">$<envar>KDEDIR</envar>/bin</filename> and make sure its
1105 permissions are set appropriately.</para></note>
1106
1107 <para>In that command line, just replace <quote>[function]</quote> with the
1108 appropriate function name, &ie; type</para>
1109
1110 <screen width="40">
1111 <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>updateNews</option></userinput>
1112 </screen>
1113
1114 <para>to make &knewsticker; check for new news items and download them if
1115 necessary.</para>
1116
1117 <sect1 id="dcop-reference">
1118 <title>&DCOP; Reference</title>
1119
1120 <para>In this section, all methods which are accessible via &knewsticker;'s
1121 &DCOP; interface are listed.</para>
1122
1123 <variablelist>
1124 <varlistentry>
1125         <term><command>updateNews</command></term>
1126         <listitem>
1127                 <para>This function forces &knewsticker; to update the internal list
1128                 of articles (&ie; it queries the list of news sources which has been
1129                 <link linkend="config-newssources">configured</link> for new news) and
1130                 downloads them when necessary.</para>
1131                 <note><para>This also works if &knewsticker; is currently in offline
1132                 mode.</para></note>
1133                 <para>Example:</para>
1134                 <screen width="40">
1135                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>updateNews</option></userinput>
1136                 </screen>
1137         </listitem>
1138 </varlistentry>
1139 <varlistentry>
1140         <term><command>reparseConfig</command></term>
1141         <listitem>
1142                 <para>The <command>reparseConfig</command> command makes &knewsticker;
1143                 reload its configuration from the configuration file. This function is
1144                 used by the <link linkend="configuration">configuration dialog</link>
1145                 to talk to &knewsticker; but you can use it if you modified the
1146                 configuration file by hand.</para>
1147                 <tip><para>The configuration file is saved in
1148                 <filename>~/.kde/share/config/knewsticker_appletrc</filename></para></tip>
1149                 <para>Example:</para>
1150                 <screen width="40">
1151                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>reparseConfig</option></userinput>
1152                 </screen>
1153         </listitem>
1154 </varlistentry>
1155 <varlistentry>
1156         <term><command>setOfflineMode [bool]</command></term>
1157         <listitem>
1158                 <para>You can call this function to define whether &knewsticker; is
1159                 currently in the offline mode (&ie; whether &knewsticker; should query
1160                 the <link linkend="config-newssources">configured news sites</link> for
1161                 new news).</para>
1162                 <para>Example:</para>
1163                 <screen width="40">
1164                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>setOfflineMode</option> <option>true</option></userinput>
1165                 </screen>
1166                 <para>to enable the offline mode, or type</para>
1167                 <screen width="40">
1168                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>setOfflineMode</option> <option>false</option></userinput>
1169                 </screen>
1170                 <para>to disable offline mode.</para>
1171         </listitem>
1172 </varlistentry>
1173 <varlistentry>
1174         <term><command>interval</command></term>
1175         <listitem>
1176                 <para>Returns the currently configured news query interval in
1177                 minutes.</para>
1178                 <para>Example:</para>
1179                 <screen width="40">
1180                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>interval</option></userinput>
1181                         30
1182                         <prompt>%</prompt>
1183                 </screen>
1184         </listitem>
1185 </varlistentry>
1186 <varlistentry>
1187         <term><command>scrollingSpeed</command></term>
1188         <listitem>
1189                 <para>Returns the currently configured scrolling speed. The returned
1190                 scrolling speed is specified in pixels per second.</para>
1191                 <para>Example:</para>
1192                 <screen width="40">
1193                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>scrollingSpeed</option></userinput>
1194                         20
1195                         <prompt>%</prompt>
1196                 </screen>
1197         </listitem>
1198 </varlistentry>
1199 <varlistentry>
1200         <term><command>mouseWheelSpeed</command></term>
1201         <listitem>
1202                 <para>Returns the number of pixels the scrolltext gets shifted
1203                 per mousewheel step.</para>
1204                 <para>Example:</para>
1205                 <screen width="40">
1206                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>mouseWheelSpeed</option></userinput>
1207                         15
1208                         <prompt>%</prompt>
1209                 </screen>
1210         </listitem>
1211 </varlistentry>
1212 <varlistentry>
1213         <term><command>scrollingDirection</command></term>
1214         <listitem>
1215                 <para>Returns an integer which corresponds to the direction the
1216                 scrolltext is scrolling in:</para>
1217                 <itemizedlist>
1218                         <listitem><para>1 = To the left</para></listitem>
1219                         <listitem><para>2 = To the right</para></listitem>
1220                         <listitem><para>3 = Upwards</para></listitem>
1221                         <listitem><para>4 = Downwards</para></listitem>
1222                         <listitem><para>5 = Upwards, rotated</para></listitem>
1223                         <listitem><para>6 = Downwards, rotated</para></listitem>
1224                 </itemizedlist>
1225                 <para>Example:</para>
1226                 <screen width="40">
1227                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>scrollingDirection</option></userinput>
1228                         1
1229                         <prompt>%</prompt>
1230                 </screen>
1231         </listitem>
1232 </varlistentry>
1233 <varlistentry>
1234         <term><command>customNames</command></term>
1235         <listitem>
1236                 <para>Returns either 'true' or 'false', depending on whether &knewsticker;
1237                 uses custom names for the news sites.</para>
1238                 <para>Example:</para>
1239                 <screen width="40">
1240                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>customNames</option></userinput>
1241                         false
1242                         <prompt>%</prompt>
1243                 </screen>
1244         </listitem>
1245 </varlistentry>
1246 <varlistentry>
1247         <term><command>endlessScrolling</command></term>
1248         <listitem>
1249                 <para>Returns either 'true' or 'false', depending on whether &knewsticker;
1250                 has the endless scrolling option enabled.</para>
1251                 <para>Example:</para>
1252                 <screen width="40">
1253                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>endlessScrolling</option></userinput>
1254                         true
1255                         <prompt>%</prompt>
1256                 </screen>
1257         </listitem>
1258 </varlistentry>
1259 <varlistentry>
1260         <term><command>scrollMostRecentOnly</command></term>
1261         <listitem>
1262                 <para>Returns either 'true' or 'false', depending on whether &knewsticker;
1263                 currently only scrolls the most recent headlines for each news
1264                 site.</para>
1265                 <para>Example:</para>
1266                 <screen width="40">
1267                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>scrollMostRecentOnly</option></userinput>
1268                         false
1269                         <prompt>%</prompt>
1270                 </screen>
1271         </listitem>
1272 </varlistentry>
1273 <varlistentry>
1274         <term><command>offlineMode</command></term>
1275         <listitem>
1276                 <para>Returns either 'true' or 'false', depending on whether &knewsticker;
1277                 is currently in offline mode.</para>
1278                 <para>Example:</para>
1279                 <screen width="40">
1280                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>offlineMode</option></userinput>
1281                         false
1282                         <prompt>%</prompt>
1283                 </screen>
1284         </listitem>
1285 </varlistentry>
1286 <varlistentry>
1287         <term><command>underlineHighlighted</command></term>
1288         <listitem>
1289                 <para>Returns either 'true' or 'false', depending on whether &knewsticker;
1290                 was told to underline the headline which is currently below the mouse
1291                 cursor.</para>
1292                 <para>Example:</para>
1293                 <screen width="40">
1294                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>underlineHighlighted</option></userinput>
1295                         true
1296                         <prompt>%</prompt>
1297                 </screen>
1298         </listitem>
1299 </varlistentry>
1300 <varlistentry>
1301         <term><command>showIcons</command></term>
1302         <listitem>
1303                 <para>Returns either 'true' or 'false', depending on whether &knewsticker;
1304                 currently shows the icon of the news site each particular headline
1305                 was published at in front of the headline.</para>
1306                 <para>Example:</para>
1307                 <screen width="40">
1308                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>showIcons</option></userinput>
1309                         true
1310                         <prompt>%</prompt>
1311                 </screen>
1312         </listitem>
1313 </varlistentry>
1314 <varlistentry>
1315         <term><command>slowedScrolling</command></term>
1316         <listitem>
1317                 <para>Returns either 'true' or 'false', depending on whether &knewsticker;
1318                 has the <quote>slowed scrolling</quote> feature activated.</para>
1319                 <para>Example:</para>
1320                 <screen width="40">
1321                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>slowedScrolling</option></userinput>
1322                         false
1323                         <prompt>%</prompt>
1324                 </screen>
1325         </listitem>
1326 </varlistentry>
1327 <varlistentry>
1328         <term><command>foregroundColor</command></term>
1329         <listitem>
1330                 <para>Returns the currently configured foreground color as a string
1331                 in the format <quote>#rrggbb</quote>, where <quote>rr</quote>,
1332                 <quote>gg</quote> and <quote>bb</quote> are two-digit hexadecimal
1333                 values representing the intensity of the red, green and blue components
1334                 in a scale of 00-ff.</para>
1335                 <para>Example:</para>
1336                 <screen width="40">
1337                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>foregroundColor</option></userinput>
1338                         #804000
1339                         <prompt>%</prompt>
1340                 </screen>
1341         </listitem>
1342 </varlistentry>
1343 <varlistentry>
1344         <term><command>backgroundColor</command></term>
1345         <listitem>
1346                 <para>Returns the currently configured background color as a string
1347                 in the format <quote>#rrggbb</quote>, where <quote>rr</quote>,
1348                 <quote>gg</quote> and <quote>bb</quote> are two-digit hexadecimal
1349                 values representing the intensity of the red, green and blue components
1350                 in a scale of 00-ff.</para>
1351                 <para>Example:</para>
1352                 <screen width="40">
1353                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>backgroundColor</option></userinput>
1354                         #0030ff
1355                         <prompt>%</prompt>
1356                 </screen>
1357         </listitem>
1358 </varlistentry>
1359 <varlistentry>
1360         <term><command>highlightedColor</command></term>
1361         <listitem>
1362                 <para>Returns the currently configured highlight color as a string
1363                 in the format <quote>#rrggbb</quote>, where <quote>rr</quote>,
1364                 <quote>gg</quote> and <quote>bb</quote> are two-digit hexadecimal
1365                 values representing the intensity of the red, green and blue components
1366                 in a scale of 00-ff.</para>
1367                 <para>Example:</para>
1368                 <screen width="40">
1369                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>highlightedColor</option></userinput>
1370                         #000080
1371                         <prompt>%</prompt>
1372                 </screen>
1373         </listitem>
1374 </varlistentry>
1375 <varlistentry>
1376         <term><command>newsSources</command></term>
1377         <listitem>
1378                 <para>Returns the list of currently registered news sources. Note that
1379                 this returns all news sources, not just the selected ones. In the
1380                 output, each news source name will be printed on a line.</para>
1381                 <para>Example:</para>
1382                 <screen width="40">
1383                         <prompt>%</prompt> <userinput><command>dcop</command> <option>knewsticker</option> <option>KNewsTicker</option> <option>newsSources</option></userinput>
1384                         Freshmeat
1385                         GNOME News
1386                         dot.kde.org
1387                         Slashdot.org
1388                         <prompt>%</prompt>
1389                 </screen>
1390         </listitem>
1391 </varlistentry>
1392 </variablelist>
1393 </sect1>
1394 </appendix>
1395
1396 &documentation.index;
1397
1398 </book>