     [file emacsver.texi not included]
     [file docstyle.texi not included]

Newsticker
**********

This manual documents Newsticker, a feed reader for Emacs.  It corresponds to Emacs version EMACSVER.

Copyright © 2004--2025 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

     (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual.''

Overview
********

Newsticker provides a Feed Reader for Emacs.  It retrieves headlines from a list of news sites, processes them, and provides frontends for reading and managing them.  (Standard headline formats are RSS and Atom which makes Newsticker an ``RSS Reader'', ``Atom Reader'' or ``Feed Aggregator''.)

Headlines (or news items) consist of a title, (mostly) a description, and a link to the full story.  The description may be a brief summary in plain text or a full HTML-formatted article.  A headline may carry enclosed data such as images, audio or video files, typically in the case of so ``podcast feeds''.

Newsticker downloads headlines asynchronously at configurable times, processes and stores them so that you can read them later.  The list of subscribed feeds, the headline processing, the presentation of the headlines and almost all other aspects of Newsticker can be customized to your liking.

Installation
************

As Newsticker is part of GNU Emacs there is no need to perform any installation steps in order to use it.

Newsticker is highly customizable.  All options have reasonable default values, so that (in most cases) it is not necessary to customize anything before you start Newsticker for the first time.

Retrieving News
***************

Newsticker downloads news periodically in the background.  This is triggered as soon as you start reading news (Reading News).

Alternatively you may use the command newsticker-start (newsticker-stop) in order to start (stop) the periodic download of news without opening the reader.

The following variables define which feeds are fetched and how this is done.

newsticker-url-list-defaults
     You may select any number of feeds from this list of (sample) news feeds.

newsticker-url-list
     All your personal news feeds are defined here.  Each feed is identified by its name and an URL.  You may set the start-time and the retrieval interval for each feed as well as the retrieval command arguments in case that the default values do not fit a certain feed.

newsticker-retrieval-method
     By default Newsticker uses Emacs's built-in download capabilities for fetching headlines.  You may change this to use an external tool like wget.  In this case you need to set newsticker-wget-name and possibly newsticker-wget-arguments.

newsticker-retrieval-interval
     The number of seconds between headline retrievals.

Headline Management
*******************

Newsticker assigns a status (or ``age'') to each headline which you can modify manually.  This makes it easy to distinguish new headlines from old ones, to keep important headlines, to hide boring headlines etc.  An item is ``new'' when it has just arrived and has not been read.  You can mark it as ``old'' when you have read it or -- if you want to keep it -- you can mark it as ``immortal''.  You can do that manually and you can define filters which do that automatically, see below.  When a headline has vanished from the feed it is automatically marked as ``obsolete'' unless it has the status ``immortal''. ``Obsolete'' headlines get removed automatically after a certain time.

newsticker-auto-mark-filter-list
     You may define any number of filters for automatically marking newly arrived headlines as ``immortal'' or ``old''.  A filter looks for a regular expression in either the title or the description of a headline and then, if the expression matches, marks the headline as ``immortal'' or as ``old''.  This is done only once, when a headline is fetched for the very first time.

newsticker-keep-obsolete-items
     Obsolete headlines are removed immediately unless newsticker-keep-obsolete-items is non-nil in which case they are kept until newsticker-obsolete-item-max-age is reached.

newsticker-automatically-mark-items-as-old
     If this is set to t then a ``new'' item becomes ``old'' as soon as it is retrieved a second time.

Reading News
************

Start Newsticker with the command M-x newsticker-show-news.  This will start the asynchronous news download and displays all available headlines.

Frontends
=========

Newsticker provides two different views for browsing, marking and reading news.  The variable newsticker-frontend determines the actual headline reader.

Treeview
--------

In this view separate windows are used for displaying feeds, headlines and their descriptions.  The feeds are shown as a tree on the left hand side, headlines of the currently selected feed are shown on the upper right side, and the full contents of the currently selected headline is shown on the lower right side.

Feeds can be placed into groups, which themselves can be placed in groups and so on.  This results in the tree which is displayed on the left.  A node represents either a feed or a group of feeds holding a subtree.  The following commands allow for managing groups.

M-a
     Add a new feed group.  Name of the new group and of the parent group must be entered.  If The name of the parent group is the new group becomes a top-level group. (newsticker-group-add-group)

M-m
     Moves a feed into a group.  The name of the group must be entered. (newsticker-group-move-feed)

The position of groups and feeds within the tree can be changed with these commands:

M-UP
M-DOWN
     Shift the currently selected feed up and down within its group.

M-S-UP
M-S-DOWN
     Shift the currently selected group up and down within its parent group.

The group settings are saved to a file either automatically when newsticker is being quit or manually when the following command is executed.

s
     Save treeview group settings.

The Treeview is updated automatically as soon as new headlines have arrived.

The Treeview is used when the variable newsticker-frontend is set to the value newsticker-treeview.  (Alternatively it can be started with the command newsticker-treeview.)

Plainview
---------

In this view all headlines of all feeds are displayed in a single buffer (*newsticker*).  The modeline in the *newsticker* buffer informs you whenever new headlines have arrived.

You may want to use imenu with Plainview, which allows for navigating with the help of a menu.  In this case add the following to your Emacs startup file (~/.emacs).

     (add-hook 'newsticker-mode-hook 'imenu-add-menubar-index)

(Note that preparing the Plainview takes significantly more time than starting the Treeview because all headlines are displayed in a single buffer.  When you have subscribed to a large amount of feeds you may find that Newsticker's efforts of minimizing rendering times, caching rendered items and so on  you may find However, when you have subscribed to a large amount of feeds you may want to give the Treeview a try.)

The Plainview is used when the variable newsticker-frontend is set to the value newsticker-plainview.  (Alternatively it can be started with the command newsticker-plainview.)

Ticker
------

Additionally, headlines can be displayed in the echo area in the style of a news ticker.

Headlines can be displayed in the echo area, either scrolling like messages in a stock-quote ticker, or just changing.  This can be started with the command newsticker-start-ticker.  It can be stopped with newsticker-stop-ticker.

The ticker by default runs continuously.  To only run it once, at a specific time interval, set the newsticker-ticker-period variable.

Navigation
==========

Navigating through the list of feeds and headlines is rather straightforward.  You may do this either with the mouse or with the keyboard.  The following key bindings are provided in both, the Treeview as well as the Plainview.

f
     Move to next feed (newsticker-next-feed, newsticker-treeview-next-feed).

F
     Move to previous feed (newsticker-previous-feed, newsticker-treeview-prev-feed).

n
     Move to next item (newsticker-next-item, newsticker-treeview-next-item).

N
     Move to next new item (possibly in another feed) (newsticker-next-new-item, newsticker-treeview-next-new-item).

p
     Move to previous item (newsticker-previous-item, newsticker-treeview-prev-item).

P
     Move to previous new item (possibly in another feed) (newsticker-previous-new-item, newsticker-treeview-prev-new-item).

Treeview
--------

j
     Enter the name of a feed and jump to it (newsticker-treeview-jump).

Marking
=======

The following key bindings are provided in both, the Treeview as well as the Plainview.

o
     Mark current item as old. (newsticker-mark-item-at-point-as-read, newsticker-treeview-mark-item-old).

i
     Mark current item as immortal.  Immortal items are kept forever. (newsticker-mark-item-at-point-as-immortal, newsticker-treeview-mark-item-immortal).

More Actions
============

View full article
-----------------

v
RET
mouse-1
     Open the link to the full article (as contained in the current headline) in your web browser newsticker-treeview-browse-url).

Get News
--------

You can force immediate download of news with the following commands.

g
     Get news for currently shown feed (newsticker-treeview-get-news).

G
     Get news for all feeds (newsticker-get-all-news).

Add More Feeds
--------------

a
     The command newsticker-add-url prompts for an URL and a name of a new feed.  It then prepares a customization buffer where the details of the new feed can be set.

Automatic Processing
********************

Apart from automatic marking of headlines (by means of filters) Newsticker provides the possibility to fully process newly arrived headlines.  Instead of reading headlines yourself you can tell Newsticker to do that for you.

In order to do so write a function which takes two arguments

FEEDNAME
     the name of the corresponding news feed,

ITEM
     the decoded headline.

and add it to newsticker-new-item-functions.  Each function contained in this list is called once for each new headline. Depending on the feed name and the contents of the new headline you can

  * automatically download images referenced in HTML-formatted descriptions (for which a function already exists, see newsticker-download-images),

  * automatically save enclosed audio and video files (for which another function exists as well, see newsticker-download-enclosures),

  * flash the screen while playing some sound,

  * whatever you want.

Configuration
*************

All Newsticker options are customizable, i.e., they can be changed with Emacs customization methods.  Call the command customize-group and enter newsticker for the customization group.

The following list shows the available groups of Newsticker options and some of the most important options.

  * newsticker-retrieval contains options that define which news feeds are retrieved and how this is done.

       * newsticker-url-list defines the list of headlines that are retrieved.

       * newsticker-retrieval-method defines how headlines are retrieved.  This is either done using Emacs's built-in download capabilities or using an external tool.

       * newsticker-retrieval-interval defines how often headlines are retrieved.

  * newsticker-headline-processing contains options that define how the retrieved headlines are processed.

       * newsticker-keep-obsolete-items decides whether unread headlines that have been removed from the feed are kept in the Newsticker cache.

       * newsticker-auto-mark-filter-list provides the possibility to automatically mark headlines as immortal or old.

  * newsticker-hooks contains options for hooking other Emacs commands to newsticker functions.

       * newsticker-new-item-functions allows for automatic processing of headlines.  See newsticker-download-images, and newsticker-download-enclosures for sample functions.

       * The subgroup newsticker-plainview-hooks contains hooks that apply to the plainview reader only.

  * newsticker-miscellaneous contains other Newsticker options.

  * newsticker-ticker contains options that define how headlines are shown in the echo area, i.e., the ``ticker''.

       * newsticker-ticker-interval, newsticker-ticker-period, and newsticker-scroll-smoothly define how headlines are shown in the echo area.

  * newsticker-reader contains options for adjusting the headline reader.

       * newsticker-frontend determines the actual headline reader.  The ``plainview'' reader uses a single buffer, the ``treeview'' uses separate buffers and windows.

       * The subgroup newsticker-plainview contains options for the plainview reader.

       * The subgroup newsticker-treeview contains options for the treeview reader.

For the complete list of options please have a look at the customization buffers.

Supported Formats
*****************

Newsticker works with the standard RSS and Atom formats listed below (being lenient with feeds which break the specifications).

RSS formats
-----------

  * RSS 0.91 (see http://backend.userland.com/rss091)

  * RSS 0.92 (see http://backend.userland.com/rss092)

  * RSS 1.0 (see http://web.resource.org/rss/1.0/spec)

  * RSS 2.0 (see https://cyber.harvard.edu/rss/rss.html)

Atom formats
------------

  * Atom 0.3

  * Atom 1.0 (see https://datatracker.ietf.org/doc/rfc4287/)

GNU Free Documentation License
******************************

     [file doclicense.texi not included]