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  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 @end titlepage
  52
  53 @contents
  54
  55 @ifnottex
  56 @node Top
  57 @top Newsticker
  58 @end ifnottex
  59
  60 @menu
  61 * Overview::        General description of newsticker.
  62 * Requirements::    Requirements for using newsticker.
  63 * Installation::    Installing newsticker on your system.
  64 * Usage::           Basic newsticker instructions.
  65 * Configuration::   Customizable newsticker settings.
  66 * Remarks::         Remarks about newsticker.
  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 should work 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", or "RSS
  98 aggregator".
  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 requires a program which can retrieve files via http and
 132 prints them to stdout.  By default Newsticker will use
 133 @uref{http://www.gnu.org/software/wget/wget.html, wget} for this task.
 134
 135
 136 @node Installation
 137 @chapter Installation
 138
 139 As Newsticker is part of GNU Emacs there is no need to perform any
 140 installation steps in order to use Newsticker.
 141
 142 However, if you are using imenu, which allows for navigating with the
 143 help of a menu, you should add the following to your Emacs startup file
 144 (@file{~/.emacs}).
 145
 146 @lisp
 147 (add-hook 'newsticker-mode-hook 'imenu-add-menubar-index)
 148 @end lisp
 149
 150 That's it.
 151
 152 @node Usage
 153 @chapter Usage
 154
 155 @findex newsticker-show-news
 156 The command @code{newsticker-show-news} will display all available
 157 headlines in a special buffer, called @samp{*newsticker*}.  It will
 158 also start the asynchronous download of headlines.  The modeline in
 159 the @samp{*newsticker*} buffer informs whenever new headlines have
 160 arrived.  Clicking mouse-button 2 or pressing RET in this buffer on a
 161 headline will call @code{browse-url} to load the corresponding news
 162 story in your favourite web browser.
 163
 164 @findex newsticker-start-ticker
 165 @findex newsticker-stop-ticker
 166 The scrolling, or flashing of headlines in the echo area, can be
 167 started with the command @code{newsticker-start-ticker}. It can be
 168 stopped with @code{newsticker-stop-ticker}.
 169
 170 @findex newsticker-start
 171 @findex newsticker-stop
 172 If you just want to start the periodic download of headlines use the
 173 command @code{newsticker-start}. Calling @code{newsticker-stop} will
 174 stop the periodic download, but will call
 175 @code{newsticker-stop-ticker} as well.
 176
 177 @node Configuration
 178 @chapter Configuration
 179
 180 All Newsticker options are customizable, i.e. they can be changed with
 181 Emacs customization methods: Call the command
 182 @code{customize-group} and enter @samp{newsticker} for the customization
 183 group.
 184
 185 All Newsticker options have reasonable default values, so that in most
 186 cases it is not necessary to customize settings before starting Newsticker
 187 for the first time.
 188
 189 Newsticker options are organized in the following groups.
 190
 191 @itemize
 192
 193 @item
 194 @code{newsticker-feed} contains options that define which news
 195 feeds are retrieved and how this is done.
 196
 197 @itemize
 198 @item
 199 @vindex newsticker-url-list
 200 @code{newsticker-url-list} defines the list of headlines which are
 201 retrieved.
 202 @item
 203 @vindex newsticker-retrieval-interval
 204 @code{newsticker-retrieval-interval} defines how often headlines
 205 are retrieved.
 206 @end itemize
 207
 208 @item
 209 @code{newsticker-headline-processing} contains options that define
 210 how the retrieved headlines are processed.
 211
 212 @itemize
 213 @item
 214 @vindex newsticker-keep-obsolete-items
 215 @code{newsticker-keep-obsolete-items} decides whether unread
 216 headlines that have been removed from the feed are kept in the
 217 Newsticker cache.
 218 @end itemize
 219
 220 @item
 221 @code{newsticker-layout} contains options that define how the
 222 buffer for reading news headlines is formatted.
 223
 224 @itemize
 225 @item
 226 @vindex newsticker-heading-format
 227 @code{newsticker-item-format} defines how the title of a headline
 228 is formatted.
 229 @end itemize
 230
 231 @item
 232 @code{newsticker-ticker} contains options that define how headlines
 233 are shown in the echo area.
 234
 235 @itemize
 236 @item
 237 @vindex newsticker-display-interval
 238 @vindex newsticker-scroll-smoothly
 239 @code{newsticker-display-interval} and
 240 @code{newsticker-scroll-smoothly} define how headlines are shown in
 241 the echo area.
 242 @end itemize
 243
 244 @item
 245 @code{newsticker-hooks} contains options for hooking other Emacs
 246 commands to newsticker functions.
 247 @itemize
 248 @item
 249 @vindex newsticker-new-item-functions
 250 @code{newsticker-new-item-functions} allows for automatic
 251 processing of headlines. See `newsticker-download-images', and
 252 `newsticker-download-enclosures' for sample functions.
 253 @end itemize
 254
 255 @item
 256 @code{newsticker-miscellaneous} contains other Newsticker options.
 257
 258 @end itemize
 259
 260 Please have a look at the customization buffers for the complete list
 261 of options.
 262
 263 @node Remarks
 264 @chapter Remarks
 265
 266 This newsticker is designed do its job silently in the background
 267 without disturbing you.  However, it is probably impossible to prevent
 268 such a tool from slightly attenuating your Editor's responsiveness
 269 every once in a while.
 270
 271 Byte-compiling newsticker.el is recommended.
 272
 273
 274
 275 @node Index
 276 @unnumbered Index
 277
 278 @printindex cp
 279
 280 @bye
 281
 282
 283
 284 @ignore
 285    arch-tag: 7a4de539-117c-4658-b799-0b9e3d0ccec0
 286 @end ignore