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, e.g., podcasts).
 109
 110 @ignore
 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 @end ignore
 121
 122 @node Requirements
 123 @chapter Requirements
 124
 125 Newsticker can be used with
 126 @uref{http://www.gnu.org/software/emacs/emacs.html, GNU Emacs} version
 127 21.1 or later as well as @uref{http://www.xemacs.org, XEmacs}.  It
 128 requires an XML-parser (@file{xml.el}), which is part of GNU Emacs.  If
 129 you are using XEmacs you want to get the @file{net-utils} package
 130 which contains @file{xml.el} for XEmacs.
 131
 132 Newsticker retrieves headlines either via Emacs's built-in retrieval
 133 functions, by an arbitrary external program that retrieves files via
 134 http and prints them to stdout (like
 135 @uref{http://www.gnu.org/software/wget/wget.html, wget}, or -- on a
 136 per feed basis -- via an arbitrary Lisp command.
 137
 138
 139 @node Installation
 140 @chapter Installation
 141
 142 As Newsticker is part of GNU Emacs there is no need to perform any
 143 installation steps in order to use Newsticker.
 144
 145 However, if you are using imenu, which allows for navigating with the
 146 help of a menu, you should add the following to your Emacs startup file
 147 (@file{~/.emacs}).
 148
 149 @lisp
 150 (add-hook 'newsticker-mode-hook 'imenu-add-menubar-index)
 151 @end lisp
 152
 153 That's it.
 154
 155 @node Usage
 156 @chapter Usage
 157
 158 @findex newsticker-show-news
 159 The command @code{newsticker-show-news} will display all available
 160 headlines.  It will also start the asynchronous download of headlines.
 161
 162 You can choose between two different frontends for reading headlines:
 163 @itemize
 164 @item Newsticker's @emph{treeview} uses separate windows for the
 165 feeds (in tree form), a list of headlines for the current feed, and
 166 the content of the current headline.  Feeds can be placed into groups,
 167 which themselves can be placed in groups and so on.
 168 @item Newsticker's @emph{plainview} displays all headlines in a
 169 single buffer, called @samp{*newsticker*}.  The modeline in the
 170 @samp{*newsticker*} buffer informs you whenever new headlines have
 171 arrived.
 172 @end itemize
 173 In both views clicking mouse-button 2 or pressing RET on a headline
 174 will call @code{browse-url} to load the corresponding news story in
 175 your favorite web browser.
 176
 177 @findex newsticker-start-ticker
 178 @findex newsticker-stop-ticker
 179 The scrolling, or flashing of headlines in the echo area, can be
 180 started with the command @code{newsticker-start-ticker}.  It can be
 181 stopped with @code{newsticker-stop-ticker}.
 182
 183 @findex newsticker-start
 184 @findex newsticker-stop
 185 If you just want to start the periodic download of headlines use the
 186 command @code{newsticker-start}.  Calling @code{newsticker-stop} will
 187 stop the periodic download, but will call
 188 @code{newsticker-stop-ticker} as well.
 189
 190 @node Configuration
 191 @chapter Configuration
 192
 193 All Newsticker options are customizable, i.e. they can be changed with
 194 Emacs customization methods.  Call the command
 195 @code{customize-group} and enter @samp{newsticker} for the customization
 196 group.
 197
 198 All Newsticker options have reasonable default values, so that in most
 199 cases it is not necessary to customize settings before starting Newsticker
 200 for the first time.
 201
 202 The following list shows the available groups of newsticker options
 203 and some of the most important options.
 204
 205 @itemize
 206
 207 @item
 208 @code{newsticker-retrieval} contains options that define which news
 209 feeds are retrieved and how this is done.
 210
 211 @itemize
 212 @item
 213 @vindex newsticker-url-list
 214 @code{newsticker-url-list} defines the list of headlines that are
 215 retrieved.
 216 @item
 217 @vindex newsticker-retrieval-method
 218 @code{newsticker-retrieval-method} defines how headlines are
 219 retrieved.  This is either done using Emacs's built-in download
 220 capabilities or using an external tool.
 221 @item
 222 @vindex newsticker-retrieval-interval
 223 @code{newsticker-retrieval-interval} defines how often headlines
 224 are retrieved.
 225 @end itemize
 226
 227 @item
 228 @code{newsticker-headline-processing} contains options that define
 229 how the retrieved headlines are processed.
 230
 231 @itemize
 232 @item
 233 @vindex newsticker-keep-obsolete-items
 234 @code{newsticker-keep-obsolete-items} decides whether unread
 235 headlines that have been removed from the feed are kept in the
 236 Newsticker cache.
 237 @item
 238 @vindex newsticker-auto-mark-filter-list
 239 @code{newsticker-auto-mark-filter-list} provides the possibility to
 240 automatically mark headlines as immortal or old.
 241 @end itemize
 242
 243 @item
 244 @code{newsticker-hooks} contains options for hooking other Emacs
 245 commands to newsticker functions.
 246 @itemize
 247 @item
 248 @vindex newsticker-new-item-functions
 249 @code{newsticker-new-item-functions} allows for automatic
 250 processing of headlines.  See @code{newsticker-download-images}, and
 251 @code{newsticker-download-enclosures} for sample functions.
 252 @item
 253 @vindex newsticker-plainview-hooks
 254 The subgroup @code{newsticker-plainview-hooks} contains hooks that
 255 apply to the plainview reader only.
 256 @end itemize
 257
 258 @item
 259 @code{newsticker-miscellaneous} contains other Newsticker options.
 260
 261 @item
 262 @code{newsticker-ticker} contains options that define how headlines
 263 are shown in the echo area, i.e. the ``ticker''.
 264
 265 @itemize
 266 @item
 267 @vindex newsticker-display-interval
 268 @vindex newsticker-scroll-smoothly
 269 @code{newsticker-ticker-interval} and
 270 @code{newsticker-scroll-smoothly} define how headlines are shown in
 271 the echo area.
 272 @end itemize
 273
 274
 275 @item
 276 @code{newsticker-reader} contains options for adjusting the headline reader.
 277
 278 @itemize
 279 @item
 280 @vindex newsticker-frontend
 281 @code{newsticker-frontend} determines the actual headline reader.  The
 282 ``plainview'' reader uses a single buffer, the ``treeview'' uses
 283 separate buffers and windows.
 284 @end itemize
 285
 286 @itemize
 287 @item
 288 @vindex newsticker-plainview
 289 The subgroup @code{newsticker-plainview} contains options for the
 290 plainview reader.
 291 @item
 292 @vindex newsticker-treeview
 293 The subgroup @code{newsticker-treeview} contains options for the
 294 treeview reader.
 295 @end itemize
 296
 297 @end itemize
 298
 299 For the complete list of options please have a look at the
 300 customization buffers.
 301
 302 @node Remarks
 303 @chapter Remarks
 304
 305 Byte-compiling newsticker.el is recommended.
 306
 307 @node GNU Free Documentation License
 308 @appendix GNU Free Documentation License
 309 @include doclicense.texi
 310
 311 @node Index
 312 @unnumbered Index
 313
 314 @printindex cp
 315
 316 @bye