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