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