man/newsticker.texi

   1 \input texinfo   @c -*-texinfo-*-
   2 @comment %**start of header
   3 @setfilename ../info/newsticker
   4 @set VERSION 1.9
   5 @set UPDATED November 2005
   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  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.2 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 in the Emacs manual.
  26
  27 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
  28 this GNU Manual, like GNU software.  Copies published by the Free
  29 Software Foundation raise funds for GNU development.''
  30
  31 This document is part of a collection distributed under the GNU Free
  32 Documentation License.  If you want to distribute this document
  33 separately from the collection, you can do so by adding a copy of the
  34 license to the document, as described in section 6 of the license.
  35 @end quotation
  36 @end copying
  37
  38 @dircategory Emacs
  39 @direntry
  40 * Newsticker: (newsticker). A Newsticker for Emacs.
  41 @end direntry
  42
  43 @titlepage
  44 @title Newsticker -- a Newsticker for Emacs
  45 @subtitle for version @value{VERSION}, @value{UPDATED}
  46 @author Ulf Jasper
  47 @author @email{ulf.jasper@@web.de}
  48 @author @uref{http://de.geocities.com/ulf_jasper}
  49 @page
  50 @vskip 0pt plus 1filll
  51 @insertcopying
  52 @end titlepage
  53
  54 @contents
  55
  56 @ifnottex
  57 @node Top
  58 @top Newsticker
  59 @end ifnottex
  60
  61 @menu
  62 * Overview::        General description of newsticker.
  63 * Requirements::    Requirements for using newsticker.
  64 * Installation::    Installing newsticker on your system.
  65 * Usage::           Basic newsticker instructions.
  66 * Configuration::   Customizable newsticker settings.
  67 * Remarks::         Remarks about newsticker.
  68 * GNU Free Documentation License:: The license for this documentation.
  69 * Index::           Variable, function, and concept index.
  70 @end menu
  71
  72 @node Overview
  73 @chapter Overview
  74
  75 Newsticker provides a newsticker for Emacs. A newsticker is a thing
  76 that asynchronously retrieves headlines from a list of news sites,
  77 prepares these headlines for reading, and allows for loading the
  78 corresponding articles in a web browser.
  79
  80
  81 Headlines consist of a title and (possibly) a small description.  They
  82 are contained in "RSS" (RDF Site Summary) or "Atom" files.  Newsticker
  83 should work with the following RSS formats:
  84
  85 @itemize
  86 @item RSS 0.91 (see @uref{http://backend.userland.com/rss091} or
  87 @uref{http://my.netscape.com/publish/formats/rss-spec-0.91.html}),
  88 @item RSS 0.92 (see @uref{http://backend.userland.com/rss092}),
  89 @item RSS 1.0 (see @uref{http://purl.org/rss/1.0/spec}
  90 @item RSS 2.0 (see @uref{http://blogs.law.harvard.edu/tech/rss}),
  91 @end itemize
  92 @itemize
  93 as well as the following Atom formats:
  94 @item Atom 0.3
  95 @item Atom 1.0 (see
  96 @uref{http://www.ietf.org/internet-drafts/draft-ietf-atompub-format-11.txt}).
  97 @end itemize
  98
  99 That makes Newsticker.el an "Atom aggregator, "RSS reader", or "RSS
 100 aggregator".
 101
 102 Newsticker provides several commands for reading headlines, navigating
 103 through them, marking them as read/unread, hiding old headlines etc.
 104 Headlines can be displayed as plain text or as rendered HTML.
 105
 106 Headlines can be displayed in the echo area, either scrolling like
 107 messages in a stock-quote ticker, or just changing.
 108
 109 Newsticker allows for automatic processing of headlines by providing
 110 hooks and (sample) functions for automatically downloading images and
 111 enclosed files (as delivered by podcasts, e.g.).
 112
 113 @ifhtml
 114 Here are screen shots of the @uref{newsticker-1.7.png, version 1.7
 115 (current version)} and some older screen shots:
 116 @uref{newsticker-1.6.png, version 1.6},
 117 @uref{newsticker-1.5.png, version 1.5},
 118 @uref{newsticker-1.4.png, version 1.4}
 119 @uref{newsticker-1.3.png, version 1.3},
 120 @uref{newsticker-1.0.png, version 1.0}.
 121 @end ifhtml
 122
 123 @node Requirements
 124 @chapter Requirements
 125
 126 Newsticker can be used with
 127 @uref{http://www.gnu.org/software/emacs/emacs.html, GNU Emacs} version
 128 21.1 or later as well as @uref{http://www.xemacs.org, XEmacs}.  It
 129 requires an XML-parser (@file{xml.el}) which is part of GNU Emacs.  If
 130 you are using XEmacs you want to get the @file{net-utils} package
 131 which contains @file{xml.el} for XEmacs.
 132
 133 Newsticker requires a program which can retrieve files via http and
 134 prints them to stdout.  By default Newsticker will use
 135 @uref{http://www.gnu.org/software/wget/wget.html, wget} for this task.
 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 in a special buffer, called @samp{*newsticker*}.  It will
 160 also start the asynchronous download of headlines.  The modeline in
 161 the @samp{*newsticker*} buffer informs whenever new headlines have
 162 arrived.  Clicking mouse-button 2 or pressing RET in this buffer on a
 163 headline will call @code{browse-url} to load the corresponding news
 164 story in your favourite web browser.
 165
 166 @findex newsticker-start-ticker
 167 @findex newsticker-stop-ticker
 168 The scrolling, or flashing of headlines in the echo area, can be
 169 started with the command @code{newsticker-start-ticker}. It can be
 170 stopped with @code{newsticker-stop-ticker}.
 171
 172 @findex newsticker-start
 173 @findex newsticker-stop
 174 If you just want to start the periodic download of headlines use the
 175 command @code{newsticker-start}. Calling @code{newsticker-stop} will
 176 stop the periodic download, but will call
 177 @code{newsticker-stop-ticker} as well.
 178
 179 @node Configuration
 180 @chapter Configuration
 181
 182 All Newsticker options are customizable, i.e. they can be changed with
 183 Emacs customization methods: Call the command
 184 @code{customize-group} and enter @samp{newsticker} for the customization
 185 group.
 186
 187 All Newsticker options have reasonable default values, so that in most
 188 cases it is not necessary to customize settings before starting Newsticker
 189 for the first time.
 190
 191 Newsticker options are organized in the following groups.
 192
 193 @itemize
 194
 195 @item
 196 @code{newsticker-feed} contains options that define which news
 197 feeds are retrieved and how this is done.
 198
 199 @itemize
 200 @item
 201 @vindex newsticker-url-list
 202 @code{newsticker-url-list} defines the list of headlines which are
 203 retrieved.
 204 @item
 205 @vindex newsticker-retrieval-interval
 206 @code{newsticker-retrieval-interval} defines how often headlines
 207 are retrieved.
 208 @end itemize
 209
 210 @item
 211 @code{newsticker-headline-processing} contains options that define
 212 how the retrieved headlines are processed.
 213
 214 @itemize
 215 @item
 216 @vindex newsticker-keep-obsolete-items
 217 @code{newsticker-keep-obsolete-items} decides whether unread
 218 headlines that have been removed from the feed are kept in the
 219 Newsticker cache.
 220 @end itemize
 221
 222 @item
 223 @code{newsticker-layout} contains options that define how the
 224 buffer for reading news headlines is formatted.
 225
 226 @itemize
 227 @item
 228 @vindex newsticker-heading-format
 229 @code{newsticker-item-format} defines how the title of a headline
 230 is formatted.
 231 @end itemize
 232
 233 @item
 234 @code{newsticker-ticker} contains options that define how headlines
 235 are shown in the echo area.
 236
 237 @itemize
 238 @item
 239 @vindex newsticker-display-interval
 240 @vindex newsticker-scroll-smoothly
 241 @code{newsticker-display-interval} and
 242 @code{newsticker-scroll-smoothly} define how headlines are shown in
 243 the echo area.
 244 @end itemize
 245
 246 @item
 247 @code{newsticker-hooks} contains options for hooking other Emacs
 248 commands to newsticker functions.
 249 @itemize
 250 @item
 251 @vindex newsticker-new-item-functions
 252 @code{newsticker-new-item-functions} allows for automatic
 253 processing of headlines. See `newsticker-download-images', and
 254 `newsticker-download-enclosures' for sample functions.
 255 @end itemize
 256
 257 @item
 258 @code{newsticker-miscellaneous} contains other Newsticker options.
 259
 260 @end itemize
 261
 262 Please have a look at the customization buffers for the complete list
 263 of options.
 264
 265 @node Remarks
 266 @chapter Remarks
 267
 268 This newsticker is designed do its job silently in the background
 269 without disturbing you.  However, it is probably impossible to prevent
 270 such a tool from slightly attenuating your Editor's responsiveness
 271 every once in a while.
 272
 273 Byte-compiling newsticker.el is recommended.
 274
 275 @node GNU Free Documentation License
 276 @appendix GNU Free Documentation License
 277 @include doclicense.texi
 278
 279 @node Index
 280 @unnumbered Index
 281
 282 @printindex cp
 283
 284 @bye
 285
 286
 287
 288 @ignore
 289    arch-tag: 7a4de539-117c-4658-b799-0b9e3d0ccec0
 290 @end ignore