doc/misc/newsticker.texi

   1 \input texinfo   @c -*-texinfo-*-
   2 @comment %**start of header
   3 @setfilename ../../info/newsticker
   4 @set VERSION 1.99
   5 @set UPDATED June 2008
   6 @settitle Newsticker @value{VERSION}
   7 @syncodeindex vr cp
   8 @syncodeindex fn cp
   9 @syncodeindex pg cp
  10 @comment %**end of header
  11
  12 @copying
  13 This manual is for Newsticker (version @value{VERSION}, @value{UPDATED}).
  14
  15 @noindent
  16 Copyright @copyright{} 2004, 2005, 2006, 2007, 2008
  17 Free Software Foundation, Inc.
  18
  19 @quotation
  20 Permission is granted to copy, distribute and/or modify this document
  21 under the terms of the GNU Free Documentation License, Version 1.2 or
  22 any later version published by the Free Software Foundation; with no
  23 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
  24 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''.
  26
  27 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
  28 modify this GNU manual.  Buying copies from the FSF supports it in
  29 developing GNU and promoting software freedom.''
  30 @end quotation
  31 @end copying
  32
  33 @dircategory Emacs
  34 @direntry
  35 * Newsticker: (newsticker). A Newsticker for Emacs.
  36 @end direntry
  37
  38 @titlepage
  39 @title Newsticker -- a Newsticker for Emacs
  40 @subtitle for version @value{VERSION}, @value{UPDATED}
  41 @author Ulf Jasper
  42 @author @email{ulf.jasper@@web.de}
  43 @author @uref{http://ulf.epplejasper.de/}
  44 @page
  45 @vskip 0pt plus 1filll
  46 @insertcopying
  47 @end titlepage
  48
  49 @contents
  50
  51 @ifnottex
  52 @node Top
  53 @top Newsticker
  54 @end ifnottex
  55
  56 @menu
  57 * Overview::        General description of newsticker.
  58 * Requirements::    Requirements for using newsticker.
  59 * Installation::    Installing newsticker on your system.
  60 * Usage::           Basic newsticker instructions.
  61 * Configuration::   Customizable newsticker settings.
  62 * Remarks::         Remarks about newsticker.
  63 * GNU Free Documentation License:: The license for this documentation.
  64 * Index::           Variable, function, and concept index.
  65 @end menu
  66
  67 @node Overview
  68 @chapter Overview
  69
  70 Newsticker provides a newsticker for Emacs. A newsticker is a thing
  71 that asynchronously retrieves headlines from a list of news sites,
  72 prepares these headlines for reading, and allows for loading the
  73 corresponding articles in a web browser.
  74
  75
  76 Headlines consist of a title and (possibly) a small description.  They
  77 are contained in "RSS" (RDF Site Summary) or "Atom" files.  Newsticker
  78 works with the following RSS formats:
  79
  80 @itemize
  81 @item RSS 0.91 (see @uref{http://backend.userland.com/rss091} or
  82 @uref{http://my.netscape.com/publish/formats/rss-spec-0.91.html}),
  83 @item RSS 0.92 (see @uref{http://backend.userland.com/rss092}),
  84 @item RSS 1.0 (see @uref{http://purl.org/rss/1.0/spec}
  85 @item RSS 2.0 (see @uref{http://blogs.law.harvard.edu/tech/rss}),
  86 @end itemize
  87 @itemize
  88 as well as the following Atom formats:
  89 @item Atom 0.3
  90 @item Atom 1.0 (see
  91 @uref{http://www.ietf.org/internet-drafts/draft-ietf-atompub-format-11.txt}).
  92 @end itemize
  93
  94 That makes Newsticker.el an ``Atom aggregator'', ``RSS reader'', ``Feed
  95 aggregator'', or ``Feed reader''.
  96
  97 Newsticker provides several commands for reading headlines, navigating
  98 through them, marking them as read/unread, hiding old headlines etc.
  99 Headlines can be displayed as plain text or as rendered HTML.
 100
 101 Headlines can be displayed in the echo area, either scrolling like
 102 messages in a stock-quote ticker, or just changing.
 103
 104 Newsticker allows for automatic processing of headlines by providing
 105 hooks and (sample) functions for automatically downloading images and
 106 enclosed files (as delivered by podcasts, e.g.).
 107
 108 @ifhtml
 109 Here are screen shots of the @uref{newsticker-1.7.png, version 1.7
 110 (current version)} and some older screen shots:
 111 @uref{newsticker-1.6.png, version 1.6},
 112 @uref{newsticker-1.5.png, version 1.5},
 113 @uref{newsticker-1.4.png, version 1.4}
 114 @uref{newsticker-1.3.png, version 1.3},
 115 @uref{newsticker-1.0.png, version 1.0}.
 116 @end ifhtml
 117
 118 @node Requirements
 119 @chapter Requirements
 120
 121 Newsticker can be used with
 122 @uref{http://www.gnu.org/software/emacs/emacs.html, GNU Emacs} version
 123 21.1 or later as well as @uref{http://www.xemacs.org, XEmacs}.  It
 124 requires an XML-parser (@file{xml.el}) which is part of GNU Emacs.  If
 125 you are using XEmacs you want to get the @file{net-utils} package
 126 which contains @file{xml.el} for XEmacs.
 127
 128 Newsticker retrieves headlines either via Emacs' built-in retrieval
 129 functions, by an arbitrary external program that retrieves files via
 130 http and prints them to stdout (like
 131 @uref{http://www.gnu.org/software/wget/wget.html, wget}, or -- on a
 132 per feed basis -- via an arbitrary Lisp command.
 133
 134
 135 @node Installation
 136 @chapter Installation
 137
 138 As Newsticker is part of GNU Emacs there is no need to perform any
 139 installation steps in order to use Newsticker.
 140
 141 However, if you are using imenu, which allows for navigating with the
 142 help of a menu, you should add the following to your Emacs startup file
 143 (@file{~/.emacs}).
 144
 145 @lisp
 146 (add-hook 'newsticker-mode-hook 'imenu-add-menubar-index)
 147 @end lisp
 148
 149 That's it.
 150
 151 @node Usage
 152 @chapter Usage
 153
 154 @findex newsticker-show-news
 155 The command @code{newsticker-show-news} will display all available
 156 headlines.  It will also start the asynchronous download of headlines.
 157
 158 You can choose between two different frontends for reading headlines:
 159 @itemize
 160 @item Newsticker's @emph{treeview} uses separate windows for the
 161 feeds (in tree form), a list of headlines for the current feed, and
 162 the content of the current headline. Feeds can be placed into groups
 163 which itself can be placed in groups and so on.
 164 @item Newsticker's @emph{plainview} displays all headlines in a
 165 single buffer, called @samp{*newsticker*}. The modeline in the
 166 @samp{*newsticker*} buffer informs whenever new headlines have
 167 arrived.
 168 @end itemize
 169 In both views clicking mouse-button 2 or pressing RET on a headline
 170 will call @code{browse-url} to load the corresponding news story in
 171 your favourite web browser.
 172
 173 @findex newsticker-start-ticker
 174 @findex newsticker-stop-ticker
 175 The scrolling, or flashing of headlines in the echo area, can be
 176 started with the command @code{newsticker-start-ticker}. It can be
 177 stopped with @code{newsticker-stop-ticker}.
 178
 179 @findex newsticker-start
 180 @findex newsticker-stop
 181 If you just want to start the periodic download of headlines use the
 182 command @code{newsticker-start}. Calling @code{newsticker-stop} will
 183 stop the periodic download, but will call
 184 @code{newsticker-stop-ticker} as well.
 185
 186 @node Configuration
 187 @chapter Configuration
 188
 189 All Newsticker options are customizable, i.e. they can be changed with
 190 Emacs customization methods: Call the command
 191 @code{customize-group} and enter @samp{newsticker} for the customization
 192 group.
 193
 194 All Newsticker options have reasonable default values, so that in most
 195 cases it is not necessary to customize settings before starting Newsticker
 196 for the first time.
 197
 198 The following list shows the available groups of newsticker options
 199 and some of the most important options.
 200
 201 @itemize
 202
 203 @item
 204 @code{newsticker-retrieval} contains options that define which news
 205 feeds are retrieved and how this is done.
 206
 207 @itemize
 208 @item
 209 @vindex newsticker-url-list
 210 @code{newsticker-url-list} defines the list of headlines which are
 211 retrieved.
 212 @item
 213 @vindex newsticker-retrieval-method
 214 @code{newsticker-retrieval-method} defines how headlines are
 215 retrieved. This is either done using Emacs' built-in download
 216 capabilities or using an external tool.
 217 @item
 218 @vindex newsticker-retrieval-interval
 219 @code{newsticker-retrieval-interval} defines how often headlines
 220 are retrieved.
 221 @end itemize
 222
 223 @item
 224 @code{newsticker-headline-processing} contains options that define
 225 how the retrieved headlines are processed.
 226
 227 @itemize
 228 @item
 229 @vindex newsticker-keep-obsolete-items
 230 @code{newsticker-keep-obsolete-items} decides whether unread
 231 headlines that have been removed from the feed are kept in the
 232 Newsticker cache.
 233 @item
 234 @vindex newsticker-auto-mark-filter-list
 235 @code{newsticker-auto-mark-filter-list} provides the possibility to
 236 automatically mark headlines as immortal or old.
 237 @end itemize
 238
 239 @item
 240 @code{newsticker-hooks} contains options for hooking other Emacs
 241 commands to newsticker functions.
 242 @itemize
 243 @item
 244 @vindex newsticker-new-item-functions
 245 @code{newsticker-new-item-functions} allows for automatic
 246 processing of headlines. See `newsticker-download-images', and
 247 `newsticker-download-enclosures' for sample functions.
 248 @item
 249 @vindex newsticker-plainview-hooks
 250 The subgroup @code{newsticker-plainview-hooks} contains hook which
 251 apply to the plainview reader only.
 252 @end itemize
 253
 254 @item
 255 @code{newsticker-miscellaneous} contains other Newsticker options.
 256
 257 @item
 258 @code{newsticker-ticker} contains options that define how headlines
 259 are shown in the echo area, i.e. the ``ticker''.
 260
 261 @itemize
 262 @item
 263 @vindex newsticker-display-interval
 264 @vindex newsticker-scroll-smoothly
 265 @code{newsticker-ticker-interval} and
 266 @code{newsticker-scroll-smoothly} define how headlines are shown in
 267 the echo area.
 268 @end itemize
 269
 270
 271 @item
 272 @code{newsticker-reader} contains options for adjusting the headline reader.
 273
 274 @itemize
 275 @item
 276 @vindex newsticker-frontend
 277 @code{newsticker-frontend} determines the actual headline reader. The
 278 ``plainview'' reader uses a single buffer, the ``treeview'' uses
 279 separate buffers and windows.
 280 @end itemize
 281
 282 @itemize
 283 @item
 284 @vindex newsticker-plainview
 285 The subgroup @code{newsticker-plainview} contains options for the
 286 plainview reader.
 287 @item
 288 @vindex newsticker-treeview
 289 The subgroup @code{newsticker-treeview} contains options for the
 290 treeview reader.
 291 @end itemize
 292
 293 @end itemize
 294
 295 For the complete list of options please have a look at the
 296 customization buffers.
 297
 298 @node Remarks
 299 @chapter Remarks
 300
 301 Byte-compiling newsticker.el is recommended.
 302
 303 @node GNU Free Documentation License
 304 @appendix GNU Free Documentation License
 305 @include doclicense.texi
 306
 307 @node Index
 308 @unnumbered Index
 309
 310 @printindex cp
 311
 312 @bye
 313
 314
 315
 316 @ignore
 317    arch-tag: 7a4de539-117c-4658-b799-0b9e3d0ccec0
 318 @end ignore