(EMACSSOURCES): Add gpl.texi.

[bpt/emacs.git] / man / newsticker.texi

\input texinfo   @c -*-texinfo-*-
@comment %**start of header
@setfilename ../info/newsticker
@set VERSION 1.9
@set UPDATED November 2005
@settitle Newsticker @value{VERSION}
@syncodeindex vr cp
@syncodeindex fn cp
@syncodeindex pg cp
@comment %**end of header

@copying
This manual is for Newsticker (version @value{VERSION}, @value{UPDATED}).

@noindent
Copyright @copyright{} 2004, 2005, 2006, 2007  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.2 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''
in the Emacs manual.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''

This document is part of a collection distributed under the GNU Free
Documentation License.  If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying

@dircategory Emacs
@direntry
* Newsticker: (newsticker). A Newsticker for Emacs.
@end direntry

@titlepage
@title Newsticker -- a Newsticker for Emacs
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Ulf Jasper
@author @email{ulf.jasper@@web.de}
@author @uref{http://de.geocities.com/ulf_jasper}
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Newsticker
@end ifnottex

@menu
* Overview::        General description of newsticker.
* Requirements::    Requirements for using newsticker.
* Installation::    Installing newsticker on your system.
* Usage::           Basic newsticker instructions.
* Configuration::   Customizable newsticker settings.
* Remarks::         Remarks about 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 newsticker for Emacs. A newsticker is a thing
that asynchronously retrieves headlines from a list of news sites,
prepares these headlines for reading, and allows for loading the
corresponding articles in a web browser.


Headlines consist of a title and (possibly) a small description.  They
are contained in "RSS" (RDF Site Summary) or "Atom" files.  Newsticker
should work with the following 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
@itemize
as well as the following Atom formats:
@item Atom 0.3
@item Atom 1.0 (see
@uref{http://www.ietf.org/internet-drafts/draft-ietf-atompub-format-11.txt}).
@end itemize

That makes Newsticker.el an "Atom aggregator, "RSS reader", or "RSS
aggregator".

Newsticker provides several commands for reading headlines, navigating
through them, marking them as read/unread, hiding old headlines etc.
Headlines can be displayed as plain text or as rendered HTML.

Headlines can be displayed in the echo area, either scrolling like
messages in a stock-quote ticker, or just changing.

Newsticker allows for automatic processing of headlines by providing
hooks and (sample) functions for automatically downloading images and
enclosed files (as delivered by podcasts, e.g.).

@ifhtml
Here are screen shots of the @uref{newsticker-1.7.png, version 1.7
(current version)} and some older screen shots:
@uref{newsticker-1.6.png, version 1.6},
@uref{newsticker-1.5.png, version 1.5}, 
@uref{newsticker-1.4.png, version 1.4}
@uref{newsticker-1.3.png, version 1.3}, 
@uref{newsticker-1.0.png, version 1.0}.
@end ifhtml

@node Requirements
@chapter Requirements

Newsticker can be used with
@uref{http://www.gnu.org/software/emacs/emacs.html, GNU Emacs} version
21.1 or later as well as @uref{http://www.xemacs.org, XEmacs}.  It
requires an XML-parser (@file{xml.el}) which is part of GNU Emacs.  If
you are using XEmacs you want to get the @file{net-utils} package
which contains @file{xml.el} for XEmacs.

Newsticker requires a program which can retrieve files via http and
prints them to stdout.  By default Newsticker will use
@uref{http://www.gnu.org/software/wget/wget.html, wget} for this task.


@node Installation
@chapter Installation

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

However, if you are using imenu, which allows for navigating with the
help of a menu, you should add the following to your Emacs startup file
(@file{~/.emacs}).

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

That's it.

@node Usage
@chapter Usage

@findex newsticker-show-news
The command @code{newsticker-show-news} will display all available
headlines in a special buffer, called @samp{*newsticker*}.  It will
also start the asynchronous download of headlines.  The modeline in
the @samp{*newsticker*} buffer informs whenever new headlines have
arrived.  Clicking mouse-button 2 or pressing RET in this buffer on a
headline will call @code{browse-url} to load the corresponding news
story in your favourite web browser.

@findex newsticker-start-ticker
@findex newsticker-stop-ticker
The scrolling, or flashing of headlines in the echo area, can be
started with the command @code{newsticker-start-ticker}. It can be
stopped with @code{newsticker-stop-ticker}.

@findex newsticker-start
@findex newsticker-stop
If you just want to start the periodic download of headlines use the
command @code{newsticker-start}. Calling @code{newsticker-stop} will
stop the periodic download, but will call
@code{newsticker-stop-ticker} as well.

@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.

All Newsticker options have reasonable default values, so that in most
cases it is not necessary to customize settings before starting Newsticker
for the first time.

Newsticker options are organized in the following groups.

@itemize

@item
@code{newsticker-feed} 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 which are
retrieved.
@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.
@end itemize

@item
@code{newsticker-layout} contains options that define how the
buffer for reading news headlines is formatted.

@itemize
@item
@vindex newsticker-heading-format
@code{newsticker-item-format} defines how the title of a headline
is formatted.
@end itemize

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

@itemize
@item
@vindex newsticker-display-interval
@vindex newsticker-scroll-smoothly
@code{newsticker-display-interval} and
@code{newsticker-scroll-smoothly} define how headlines are shown in
the echo area.
@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 `newsticker-download-images', and
`newsticker-download-enclosures' for sample functions.
@end itemize

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

@end itemize

Please have a look at the customization buffers for the complete list
of options.

@node Remarks
@chapter Remarks

This newsticker is designed do its job silently in the background
without disturbing you.  However, it is probably impossible to prevent
such a tool from slightly attenuating your Editor's responsiveness
every once in a while.

Byte-compiling newsticker.el is recommended.

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

@node Index
@unnumbered Index

@printindex cp

@bye



@ignore
   arch-tag: 7a4de539-117c-4658-b799-0b9e3d0ccec0
@end ignore