newsticker.texi 9.66 KB
Newer Older
Glenn Morris's avatar
Glenn Morris committed
1 2
\input texinfo   @c -*-texinfo-*-
@comment %**start of header
3
@setfilename ../../info/newsticker
Ulf Jasper's avatar
Ulf Jasper committed
4 5
@set VERSION 1.99
@set UPDATED June 2008
Glenn Morris's avatar
Glenn Morris committed
6 7 8 9 10 11 12 13 14 15
@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
16 17
Copyright @copyright{} 2004, 2005, 2006, 2007, 2008
Free Software Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
18 19 20 21 22 23 24

@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
25
is included in the section entitled ``GNU Free Documentation License''.
Glenn Morris's avatar
Glenn Morris committed
26

27 28 29
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual.  Buying copies from the FSF supports it in
developing GNU and promoting software freedom.''
Glenn Morris's avatar
Glenn Morris committed
30 31 32 33 34 35 36 37 38 39 40 41 42
@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}
Ulf Jasper's avatar
Ulf Jasper committed
43
@author @uref{http://ulf.epplejasper.de/}
Glenn Morris's avatar
Glenn Morris committed
44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
@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
Ulf Jasper's avatar
Ulf Jasper committed
78
works with the following RSS formats:
Glenn Morris's avatar
Glenn Morris committed
79 80 81 82 83 84 85 86 87 88 89 90 91 92 93

@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

Ulf Jasper's avatar
Ulf Jasper committed
94 95
That makes Newsticker.el an ``Atom aggregator'', ``RSS reader'', ``Feed
aggregator'', or ``Feed reader''.
Glenn Morris's avatar
Glenn Morris committed
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127

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.

Ulf Jasper's avatar
Ulf Jasper committed
128 129 130 131 132
Newsticker retrieves headlines either via Emacs' built-in retrieval
functions, by an arbitrary external program that retrieves files via
http and prints them to stdout (like
@uref{http://www.gnu.org/software/wget/wget.html, wget}, or -- on a
per feed basis -- via an arbitrary Lisp command.
Glenn Morris's avatar
Glenn Morris committed
133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155


@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
Ulf Jasper's avatar
Ulf Jasper committed
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171
headlines.  It will also start the asynchronous download of headlines.

You can choose between two different frontends for reading headlines:
@itemize
@item Newsticker's @emph{treeview} uses separate windows for the
feeds (in tree form), a list of headlines for the current feed, and
the content of the current headline. Feeds can be placed into groups
which itself can be placed in groups and so on. 
@item Newsticker's @emph{plainview} displays all headlines in a
single buffer, called @samp{*newsticker*}. The modeline in the
@samp{*newsticker*} buffer informs whenever new headlines have
arrived.
@end itemize
In both views clicking mouse-button 2 or pressing RET on a headline
will call @code{browse-url} to load the corresponding news story in
your favourite web browser.
Glenn Morris's avatar
Glenn Morris committed
172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197

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

Ulf Jasper's avatar
Ulf Jasper committed
198 199
The following list shows the available groups of newsticker options
and some of the most important options.
Glenn Morris's avatar
Glenn Morris committed
200 201 202 203

@itemize

@item
Ulf Jasper's avatar
Ulf Jasper committed
204
@code{newsticker-retrieval} contains options that define which news
Glenn Morris's avatar
Glenn Morris committed
205 206 207 208 209 210 211 212
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
Ulf Jasper's avatar
Ulf Jasper committed
213 214 215 216 217
@vindex newsticker-retrieval-method
@code{newsticker-retrieval-method} defines how headlines are
retrieved. This is either done using Emacs' built-in download
capabilities or using an external tool.
@item
Glenn Morris's avatar
Glenn Morris committed
218 219 220 221 222 223 224 225 226 227 228 229 230 231 232
@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.
Ulf Jasper's avatar
Ulf Jasper committed
233 234 235 236
@item
@vindex newsticker-auto-mark-filter-list
@code{newsticker-auto-mark-filter-list} provides the possibility to
automatically mark headlines as immortal or old.
Glenn Morris's avatar
Glenn Morris committed
237 238 239
@end itemize

@item
Ulf Jasper's avatar
Ulf Jasper committed
240 241
@code{newsticker-hooks} contains options for hooking other Emacs
commands to newsticker functions. 
Glenn Morris's avatar
Glenn Morris committed
242 243
@itemize
@item
Ulf Jasper's avatar
Ulf Jasper committed
244 245 246 247 248 249 250 251
@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.
@item
@vindex newsticker-plainview-hooks
The subgroup @code{newsticker-plainview-hooks} contains hook which
apply to the plainview reader only.
Glenn Morris's avatar
Glenn Morris committed
252 253
@end itemize

Ulf Jasper's avatar
Ulf Jasper committed
254 255 256
@item
@code{newsticker-miscellaneous} contains other Newsticker options.

Glenn Morris's avatar
Glenn Morris committed
257 258
@item
@code{newsticker-ticker} contains options that define how headlines
Ulf Jasper's avatar
Ulf Jasper committed
259
are shown in the echo area, i.e. the ``ticker''.
Glenn Morris's avatar
Glenn Morris committed
260 261 262 263 264

@itemize
@item
@vindex newsticker-display-interval
@vindex newsticker-scroll-smoothly
Ulf Jasper's avatar
Ulf Jasper committed
265
@code{newsticker-ticker-interval} and
Glenn Morris's avatar
Glenn Morris committed
266 267 268 269
@code{newsticker-scroll-smoothly} define how headlines are shown in
the echo area.
@end itemize

Ulf Jasper's avatar
Ulf Jasper committed
270

Glenn Morris's avatar
Glenn Morris committed
271
@item
Ulf Jasper's avatar
Ulf Jasper committed
272 273
@code{newsticker-reader} contains options for adjusting the headline reader.

Glenn Morris's avatar
Glenn Morris committed
274 275
@itemize
@item
Ulf Jasper's avatar
Ulf Jasper committed
276 277 278 279
@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.
Glenn Morris's avatar
Glenn Morris committed
280 281
@end itemize

Ulf Jasper's avatar
Ulf Jasper committed
282
@itemize
Glenn Morris's avatar
Glenn Morris committed
283
@item
Ulf Jasper's avatar
Ulf Jasper committed
284 285 286 287 288 289 290 291
@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
Glenn Morris's avatar
Glenn Morris committed
292 293 294

@end itemize

Ulf Jasper's avatar
Ulf Jasper committed
295 296
For the complete list of options please have a look at the
customization buffers.
Glenn Morris's avatar
Glenn Morris committed
297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318

@node Remarks
@chapter Remarks

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