 _____ _      _
|_   _(_) ___| | _____ _ __   BBC News Ticker
  | | | |/ __| |/ / _ \ '__|  Version 0.86, 5 April 2007
  | | | | (__|	 <  __/ |      Darren Salt 2001-2007
  |_| |_|\___|_|\_\___|_|


What is Ticker?
===============

  Ticker is a simple news ticker that uses the BBC News Online ticker or any
  RSS ticker to provide its content and links to the full stories.

  On startup, Ticker will try to contact the chosen ticker server (through a
  proxy, if you want) to collect news. After a few seconds, if successful,
  you will see a selection of news headlines being scrolled along in a
  window; else you will see a short message saying why no news headlines are
  shown.

  Ticker uses the CryptRandom module for proxy authentication (where
  required).

 Requirements
 ------------

  WindowManager 3.98 or later ("Nested WIMP").
  32-bit Shared C Library; http://www.iyonix.com/32bit/system.shtml

 Unicode and UTF-8
 -----------------

  Ticker understands UTF-8; it will, if needed, convert automatically to
  ISO-8859-1. It does not (yet) convert _to_ UTF-8.


Controlling Ticker
==================

  With the ticker window visible and showing headlines, you can click Select
  on a headline to view it in your browser. A clickable headline is
  highlighted in blue when the pointer is over it; also, the pointer's shape
  is changed.

  If you click Adjust on a headline, the ticker will be paused and, if there
  is a description associated with the headline, it will be displayed.
  Clicking Adjust again will unpause the ticker; moving the pointer away from
  the headline will also, and close the description window. Ctrl-Select and
  Ctrl-Adjust can be used to scroll the description.

  If you hold down Adjust for a second or so, the ticker will (after a short
  time) be scrolled at a faster rate until you next click in the ticker
  window, when the scrolling rate will be restored to normal.

  The ticker window is an ordinary title bar with an overlaid pane which
  contains the ticker text or status information, or possibly nothing at all.
  Adjust-clicking on the Close icon will toggle whether the window is
  minimised. Maximising it may trigger an update.

  When the ticker window is closed, it is neither scrolled nor updated. When
  it's minimised, it may still be updated unless you've configured Ticker not
  to update when this is so.

  Clicking Select on the iconbar icon will open and maximise the ticker
  window; clicking Shift-Select will open and minimise it. Clicking Adjust
  will open the configuration window. (Equivalent options may be found in the
  iconbar and ticker menus.)

  You can drag any URL or URI file which contains an HTTP URL to the Ticker
  icon or window. The ticker will be fetched and, if it's RDF or RSS,
  displayed in the ticker window.

 Menus
 -----

  * The iconbar menu

    Nothing which needs explanation, except for the 'Ticker' entry. Clicking
    on this will open the ticker window, fetching the currently selected
    server if need be; selecting from the submenu will cause Ticker to fetch
    the selected ticker.

  * The ticker menu

    The 'Control' submenu contains some options which directly affect the
    ticker window: "Update", which will immediately try to refetch the ticker
    text; "Ticker", from which you can fetch other tickers; "Abort", which
    stops an in-progress update; "Restart", which will refresh the ticker
    display and restart the scroller; either "Maximise", which extends the
    ticker window to the configured width, or "Minimise", which reduces it to
    just enough to allow you to move it and open its menu; and Reposition,
    which puts the ticker window at its configured position.

    There are two save options there, one for the link under the pointer
    (when the menu was opened), and one to save all of the ticker text and
    links (not those in deselected topics, if you're using the BBC News
    ticker) as text or HTML.

    NOTE: The ticker will not be scrolled while this menu is open and a story
    is highlighted.

  Both menus have a 'Go to' submenu. The content of this is dependent
  entirely on the ticker (except for BBC News, for which two items are
  supplied by Ticker if none are otherwise supplied). The submenu becomes
  available when ticker data has been fetched and remains so until the data
  is refreshed.

 When are the headlines refreshed?
 ---------------------------------

  For the headlines to be refreshed, the "automatically update" option must
  be enabled and the configured "update after" time must have passed since
  the last fetch. Also, one of the following conditions must hold:

  * When the ticker window is open and the last headline has been scrolled
    out of view.
  * When the ticker window is minimised (and Ticker is configured to update
    when minimised).
  * When the ticker window is opened (or maximised) from the iconbar icon or
    menu.

 Current status
 --------------

  The iconbar icon displays an "LED" which shows the primary status of
  Ticker. This is very much "traffic lights" in style:

    Red:   Headlines are unavailable for some reason.
    Amber: Headlines are being fetched.
    Green: Headlines are available.

  The ticker window, unless headlines are available, shows a longer
  description of the current state. In 'red' mode, this will normally be an
  error, or perhaps no ticker data has been fetched yet; in 'amber' mode,
  this will normally be some text which describes what Ticker's currently
  doing.


Using a proxy
=============

  Ticker can be configured to request the ticker data through a proxy.

  If you are behind a firewall, you may need to use a proxy server. If you
  don't know what the proxy's address is, ask your network manager or find
  out from your ISP.

  Ticker expects the proxy details to be entered in the format "host:port".
  You may find that you are given instructions which tell you to enter
  something like "http://www-cache.foo.bar:8080/"; for Ticker, you would
  enter "www-cache.foo.bar:8080".

  You may wish to use a proxy server on your machine, e.g. for WebCache
  running on port 80, you would use "localhost:80" or "127.0.0.1:80".

 Proxies which require authentication
 ------------------------------------

  Ticker has support for proxies which require authentication. Each time that
  you run Ticker, if it finds that the proxy requires authentication, you
  will be asked for your user name and password; Ticker will remember this
  until quit or a different proxy is used, and will ask again if the proxy
  rejects your user name or password.

  Both basic (insecure) and digest (less insecure) methods are supported; the
  basic support works and has been used Out There, and the digest support has
  been tested locally against a development version of Squid 2.5.

  If you find that you need support for some other authentication scheme such
  as NTLM, I suggest that you add it yourself and send me the patches. I may
  attempt to add it myself if asked, but testing is a little awkward :-)

 What do you mean, the proxy isn't available?
 --------------------------------------------

  If for some reason Ticker cannot connect to the proxy, it will inform you
  that it is bypassing it; it will then attempt to make a direct connection
  to the ticker server (subject to upstream transparent proxies). If you have
  entered any proxy authentication details, these will NOT be passed on.


Configuring Ticker
==================

  The configuration window is in four parts:

  * Connection

    + Ticker
      - Default: BBC News

      This option controls which ticker is selected when you next run Ticker.
      (The ticker must be listed in the saved Tickers configuration, else
      Ticker will default to BBC News.)

    + Use proxy
      - Default: no, no proxy

      This controls whether we're using a proxy, and tells Ticker where to
      find it. The format is "host:port"; http is assumed.

      See the section "Using a proxy" for more details.

    + Update every ... minutes
      - Default: yes, 15

      This controls the minimum time after the previous fetch was completed
      before which Ticker will automatically refetch the headlines.

      + As specified by the ticker
	- Default: yes

	Use the ticker-specified update period if it's present, valid and
	longer than your configured update period.

    + Don't update when minimised
      - Default: no

      If this is enabled, then Ticker won't refetch the headlines when it's
      minimised.

    + Don't update unless this variable is set
      - Default: null

      If a system variable name is given here, Ticker will check it before
      attempting to fetch the ticker data. If the variable is not set, then
      any already fetched headlines will be redisplayed.

  * Startup

    + Start up with the ticker window...
      - Default: open

      The ticker window will be opened in the requested state when you next
      run Ticker.

      + Don't fetch until first opened
	- Default: yes

	Delay the first fetch of ticker data until the ticker window is
	opened. (The "minimised" state is treated as "closed" for this
	purpose.)

    + No iconbar icon
      - Default: no (icon is present)

      This controls whether Ticker's iconbar icon is present. If not, then
      the ticker window will be opened to at least its minimised state, and
      clicking on its Close icon will exit Ticker.

  * Appearance

    + Scroll rate (OS units per second)
      - Default: 50

      Ticker will try to maintain this scroll rate as best it can.

    + Fast scroll rate (OS units per second)
      - Default: 150

      This is used when you click and hold Adjust over the Ticker scroller
      area.

    + Pause when
      - Default: never

      The ticker window will not be scrolled while the selected condition is
      true.

    + Highlight
      - Default: 8 (desktop blue)

      This is the colour used when highlighting a headline.

    + Automatically show descriptions
      - Default: no

      This controls whether the description, if present, is automatically
      shown when the pointer is over a headline.

    + Bring to front when updating
      - Default: yes

      This controls whether the ticker window is brought to the front when
      ticker text is being fetched.

  * Position

    + Window width
      - Default: 100% of screen width

      This sets the ticker window width. The width may be interpreted as
      either a percentage or a number of OS units (normally, 2 OS units per
      pixel); additionally, you can tell Ticker to interpret it as so much
      less than the screen width (useful if you want a fixed amount of space
      for something else).

    + Alignment
      - Default: left, at the top

      This pair of settings controls the position of the ticker window when
      it is opened.

    + Offset
      - Default: 0,0

      This is the offset from the given alignment. The numbers are signed,
      although the signs are used only for the centre and icon bar
      alignments.

      Clicking on 'Read' will set the offset according to the current ticker
      window position, relative to the alignment settings which are currently
      in use (rather than displayed in the configuration window).

    + Always on top
      - Default: no

      If selected, the ticker window will always be on top of other windows
      (except for other foreground windows). It uses the "foreground" option
      provided in RISC OS 4.

    + Try these settings

      Clicking on this causes the displayed settings to be applied
      immediately (and temporarily).

    + Use the defaults

      Clicking on this causes the stored settings to be reapplied.

  * Selection

    This pane applies only to the BBC News ticker.

    + Fetch 'low graphics' pages
      - Default: no

      The BBC News website has two pages for each story. One has lots of
      extra graphics such as logos, and the other has only those images
      directly related to the story. This option controls whether the
      high-graphics or low-graphics versions of news pages are fetched. If
      you are on a low-bandwidth connection or just don't want the images,
      you should select this option.

  The usual 'Cancel', 'Save' and 'OK' icons are present; also there is a
  'Default' icon which will redisplay the saved options if you click Select
  or the defaults if you click Adjust.


Tickers configuration
=====================

  You can drag any URL or URI file which contains an HTTP URL to this window.
  Details will be filled in from the file.

  Ticker   Some text which Ticker uses to identify a ticker.
  Label	   The label currently used for this ticker. Unless you're changing
	   it, it will be the same as above.
  Group	   The group in which this ticker appears. This may be left blank.
  http://  The URL of the ticker data. This is of the form "host/path" or
	   "host:port/path"; Ticker pretends that the 'http://' prefix is
	   present, and will complain if you use it :-)

  New ticker: Create a blank entry ready for details of another ticker.
  Undo:	      Restore the displayed ticker's details.
  Delete:     Forget about the displayed ticker. It remains on display,
	      though, so that you can undo the change by clicking on...
  Accept:     Change the details for a known ticker, or add details for a
	      'new' ticker.

  Reset:      Read in the default tickers list. If you click Select, then
	      existing entries are preserved; if you click Adjust, existing
	      entries may be overwritten.
  Reload:     Load the saved tickers list. This will DISCARD any unsaved
	      ticker details WITHOUT prompting you, so be careful!
  Close:      Closes the window without committing any changes.
  Save:	      Save the tickers list.

  Clicking Menu over this window will allow you to save the displayed
  information as a URL or URI file.


Command line use
================

  *<Ticker$Dir> -h|--html|-t|--text [-a|--all] [ticker label] > out/html

    will cause Ticker to run in single-tasking mode, fetching the headlines
    and outputting a simple HTML page or plain text. It will work well in a
    taskwindow.

    This relies on the saved configuration; -a or --all used to, if using the
    BBC News ticker, cause all topics to be listed. It is retained for
    compatibility reasons.

  Examples:
    *<Ticker$Dir> --text --all "BBC News" > bbc/html
    *<Ticker$Dir> -h slashdot > sd/html



Licence
=======

  GNU GPL, version 2 or later; see !Ticker.Docs.Licence.


Contact
=======

  ds@youmustbejoking.demon.co.uk

  http://www.youmustbejoking.demon.co.uk/
  http://www.youmustbejoking.demon.co.uk/progs.apps.html#ticker
