Eldoc setup code enhancements

[emacs.git] / doc / misc / newsticker.texi

\input texinfo   @c -*-texinfo-*-
@comment %**start of header
@setfilename ../../info/newsticker.info
@include emacsver.texi
@set VERSION @value{EMACSVER}
@settitle Newsticker @value{VERSION}
@syncodeindex vr cp
@syncodeindex fn cp
@syncodeindex pg cp
@documentencoding UTF-8
@comment %**end of header

@copying
This manual documents Newsticker, a feed reader for Emacs.  It
corresponds to Emacs version @value{EMACSVER}.

@noindent
Copyright @copyright{} 2004--2014 Free Software Foundation, Inc.

@quotation
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.''
@end quotation
@end copying

@dircategory Emacs network features
@direntry
* Newsticker: (newsticker).     A feed reader for Emacs.
@end direntry

@titlepage
@title Newsticker---a feed reader for Emacs
@author Ulf Jasper
@author @email{ulf.jasper@@web.de}
@author @uref{http://ulf.epplejasper.de/}
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Newsticker

@insertcopying

@end ifnottex

@menu
* Overview::             What is Newsticker?
* Installation::         Things to do before starting Newsticker the first time.
* Retrieving News::      How Newsticker fetches headlines.
* Headline Management::  How Newsticker stores headlines.
* Reading News::         How to read RSS and Atom feeds with Newsticker.
* Automatic Processing:: Automatically process news items.
* Configuration::        Customize Newsticker to your liking.
* Supported Formats::    RSS and Atom formats supported by Newsticker.

* GNU Free Documentation License:: The license for this documentation.
* Index::                          Variable, function, and concept index.
@end menu

@node Overview
@chapter Overview

Newsticker provides a @b{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.

@node Installation
@chapter 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.

@node Retrieving News
@chapter Retrieving News

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

@findex newsticker-start
@findex newsticker-stop
Alternatively you may use the command @code{newsticker-start}
(@code{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.

@table @code
@vindex newsticker-url-list-defaults
@item newsticker-url-list-defaults
You may select any number of feeds from this list of (sample) news feeds.

@vindex newsticker-url-list
@item 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.

@vindex newsticker-retrieval-method
@vindex newsticker-wget-name
@vindex newsticker-wget-arguments
@item 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
@code{wget}.  In this case you need to set @code{newsticker-wget-name}
and possibly @code{newsticker-wget-arguments}.

@vindex newsticker-retrieval-interval
@item newsticker-retrieval-interval
The number of seconds between headline retrievals.
@end table

@node Headline Management
@chapter Headline Management

@cindex Age
@cindex Status

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.

@table @code
@cindex Filter
@vindex newsticker-auto-mark-filter-list
@item 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.

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

@vindex newsticker-automatically-mark-items-as-old
@item 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.

@end table

@node Reading News
@chapter Reading News

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

@menu
* Frontends::        Select the way headlines are displayed.
* Navigation::       Move to the next unread headline etc.
* Marking::          Mark important headlines.
* More Actions::     Add new feeds etc..
@end menu

@node Frontends
@section Frontends
@cindex Frontends

@vindex newsticker-frontend
Newsticker provides two different @i{views} for browsing, marking and
reading news.  The variable @code{newsticker-frontend} determines the
actual headline reader.

@subheading Treeview
@cindex 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.

@table @kbd
@item M-a
@kindex M-a
@findex newsticker-group-add-group
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. (@code{newsticker-group-add-group})
@item M-m
@kindex M-m
@findex newsticker-group-move-feed
Moves a feed into a group. The name of the group must be
entered. (@code{newsticker-group-move-feed})
@end table

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

@table @kbd
@item M-up
@itemx M-down
@kindex M-up
@kindex M-down
@findex newsticker-group-shift-feed-up
@findex newsticker-group-shift-feed-down
Shift the currently selected feed up and down within its group.
@item M-S-up
@itemx M-S-down
@kindex M-S-up
@kindex M-S-down
@findex newsticker-group-shift-group-up
@findex newsticker-group-shift-group-down
Shift the currently selected group up and down within its parent group.
@end table

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

@table @kbd
@item s
@kindex s
@findex newsticker-treeview-save
Save treeview group settings.
@end table

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

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

@subheading Plainview
@cindex Plainview

In this view all headlines of all feeds are displayed in a single
buffer (@file{*newsticker*}). The modeline in the @file{*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 (@file{~/.emacs}).

@lisp
(add-hook 'newsticker-mode-hook 'imenu-add-menubar-index)
@end lisp

(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 @code{newsticker-frontend} is
set to the value @code{newsticker-plainview}. (Alternatively it can be
started with the command @code{newsticker-plainview}.)

@subheading Ticker
@cindex Ticker

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

@findex newsticker-start-ticker
@findex newsticker-stop-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 @code{newsticker-start-ticker}.  It can be
stopped with @code{newsticker-stop-ticker}.


@node Navigation
@section Navigation
@cindex 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.

@table @kbd
@item f
@findex newsticker-next-feed
@findex newsticker-treeview-next-feed
Move to next feed (@code{newsticker-next-feed},
@code{newsticker-treeview-next-feed}).
@item F
@findex newsticker-previous-feed
@findex newsticker-treeview-prev-feed
Move to previous feed (@code{newsticker-previous-feed},
@code{newsticker-treeview-prev-feed}).
@item n
@findex newsticker-next-item
@findex newsticker-treeview-next-item
Move to next item (@code{newsticker-next-item},
@code{newsticker-treeview-next-item}).
@item N
@findex newsticker-next-new-item
@findex newsticker-treeview-next-new-item
Move to next new item (possibly in another feed)
(@code{newsticker-next-new-item},
@code{newsticker-treeview-next-new-item}).
@item p
@findex newsticker-previous-item
@findex newsticker-treeview-prev-item
Move to previous item (@code{newsticker-previous-item},
@code{newsticker-treeview-prev-item}).
@item P
@findex newsticker-previous-new-item
@findex newsticker-treeview-prev-new-item
Move to previous new item (possibly in another feed)
(@code{newsticker-previous-new-item},
@code{newsticker-treeview-prev-new-item}).
@end table

@subheading Treeview
@table @kbd
@item j
@findex newsticker-treeview-jump
Enter the name of a feed and jump to it
(@code{newsticker-treeview-jump}).
@end table


@node Marking
@section Marking
@cindex Marking

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

@table @kbd
@item o
@findex newsticker-mark-item-at-point-as-read
@findex newsticker-treeview-mark-item-old
Mark current item as old.
(@code{newsticker-mark-item-at-point-as-read},
@code{newsticker-treeview-mark-item-old}).
@item i
@findex newsticker-mark-item-at-point-as-immortal
@findex newsticker-treeview-mark-item-immortal
Mark current item as immortal.  Immortal items are kept forever.
(@code{newsticker-mark-item-at-point-as-immortal},
@code{newsticker-treeview-mark-item-immortal}).
@end table

@node More Actions
@section More Actions
@cindex More Actions

@subheading View full article
@table @kbd
@cindex Get News
@item v
@itemx RET
@itemx <mouse-1>
@findex newsticker-treeview-browse-url
Open the link to the full article (as contained in the current
headline) in your web browser @code{newsticker-treeview-browse-url}).
@end table

@subheading Get News
@cindex Get News

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

@table @kbd
@item g
@findex newsticker-treeview-get-news
Get news for currently shown feed (@code{newsticker-treeview-get-news}).
@item G
@findex newsticker-get-all-news
Get news for all feeds (@code{newsticker-get-all-news}).
@end table

@subheading Add More Feeds
@cindex Add More Feeds

@table @kbd
@item a
@findex newsticker-add-url
The command @code{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.
@end table


@node Automatic Processing
@chapter Automatic Processing
@cindex 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.

@vindex newsticker-new-item-functions
In order to do so write a function which takes three arguments

@table @var
@item FEED
the name of the corresponding news feed,
@item TITLE
the title of the headline,
@item DESC
the decoded description of the headline.
@end table

and add it to @code{newsticker-new-item-functions}.  Each function
contained in this list is called once for each new headline.
Depending on the feed, the title and the description of a headline you
can

@itemize
@item
automatically download images referenced in HTML-formatted
descriptions (for which a function already exists, see
@code{newsticker-download-images}),
@item
automatically save enclosed audio and video files (for which another
function exists as well, see @code{newsticker-download-images}),
@item
flash the screen while playing some sound,
@item
whatever you want.
@end itemize

@node Configuration
@chapter Configuration

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

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

@itemize

@item
@code{newsticker-retrieval} contains options that define which news
feeds are retrieved and how this is done.

@itemize
@item
@vindex newsticker-url-list
@code{newsticker-url-list} defines the list of headlines that are
retrieved.
@item
@vindex newsticker-retrieval-method
@code{newsticker-retrieval-method} defines how headlines are
retrieved.  This is either done using Emacs's built-in download
capabilities or using an external tool.
@item
@vindex newsticker-retrieval-interval
@code{newsticker-retrieval-interval} defines how often headlines
are retrieved.
@end itemize

@item
@code{newsticker-headline-processing} contains options that define
how the retrieved headlines are processed.

@itemize
@item
@vindex newsticker-keep-obsolete-items
@code{newsticker-keep-obsolete-items} decides whether unread
headlines that have been removed from the feed are kept in the
Newsticker cache.
@item
@vindex newsticker-auto-mark-filter-list
@code{newsticker-auto-mark-filter-list} provides the possibility to
automatically mark headlines as immortal or old.
@end itemize

@item
@code{newsticker-hooks} contains options for hooking other Emacs
commands to newsticker functions.
@itemize
@item
@vindex newsticker-new-item-functions
@code{newsticker-new-item-functions} allows for automatic
processing of headlines.  See @code{newsticker-download-images}, and
@code{newsticker-download-enclosures} for sample functions.
@item
@vindex newsticker-plainview-hooks
The subgroup @code{newsticker-plainview-hooks} contains hooks that
apply to the plainview reader only.
@end itemize

@item
@code{newsticker-miscellaneous} contains other Newsticker options.

@item
@code{newsticker-ticker} contains options that define how headlines
are shown in the echo area, i.e., the ``ticker''.

@itemize
@item
@vindex newsticker-display-interval
@vindex newsticker-scroll-smoothly
@code{newsticker-ticker-interval} and
@code{newsticker-scroll-smoothly} define how headlines are shown in
the echo area.
@end itemize


@item
@code{newsticker-reader} contains options for adjusting the headline reader.

@itemize
@item
@vindex newsticker-frontend
@code{newsticker-frontend} determines the actual headline reader.  The
``plainview'' reader uses a single buffer, the ``treeview'' uses
separate buffers and windows.
@end itemize

@itemize
@item
@vindex newsticker-plainview
The subgroup @code{newsticker-plainview} contains options for the
plainview reader.
@item
@vindex newsticker-treeview
The subgroup @code{newsticker-treeview} contains options for the
treeview reader.
@end itemize

@end itemize

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

@node Supported Formats
@appendix Supported Formats
@cindex Supported Formats

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

@subheading RSS formats

@itemize
@item RSS 0.91 (see @uref{http://backend.userland.com/rss091} or
@uref{http://my.netscape.com/publish/formats/rss-spec-0.91.html})
@item RSS 0.92 (see @uref{http://backend.userland.com/rss092})
@item RSS 1.0 (see @uref{http://purl.org/rss/1.0/spec})
@item RSS 2.0 (see @uref{http://blogs.law.harvard.edu/tech/rss})
@end itemize

@subheading Atom formats

@itemize
@item Atom 0.3
@item Atom 1.0 (see
@uref{https://datatracker.ietf.org/doc/rfc4287/})
@end itemize


@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi

@node Index
@unnumbered Index
@printindex cp


@bye