man/newsticker.texi

   1 \input texinfo   @c -*-texinfo-*-
   2 @comment %**start of header
   3 @setfilename ../info/newsticker
   4 @set VERSION 1.8
   5 @settitle Newsticker @value{VERSION}
   6 @syncodeindex vr cp
   7 @syncodeindex fn cp
   8 @syncodeindex pg cp
   9 @comment %**end of header
  10
  11 @copying
  12 This manual is for Newsticker (version @value{VERSION}, @value{UPDATED}).
  13
  14 @noindent
  15 Copyright @copyright{} 2004, 2005  Free Software Foundation, Inc.
  16
  17 @quotation
  18 Permission is granted to copy, distribute and/or modify this document
  19 under the terms of the GNU Free Documentation License, Version 1.2 or
  20 any later version published by the Free Software Foundation; with no
  21 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
  22 and with the Back-Cover Texts as in (a) below.  A copy of the license
  23 is included in the section entitled ``GNU Free Documentation License''
  24 in the Emacs manual.
  25
  26 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
  27 this GNU Manual, like GNU software.  Copies published by the Free
  28 Software Foundation raise funds for GNU development.''
  29
  30 This document is part of a collection distributed under the GNU Free
  31 Documentation License.  If you want to distribute this document
  32 separately from the collection, you can do so by adding a copy of the
  33 license to the document, as described in section 6 of the license.
  34 @end quotation
  35 @end copying
  36
  37 @dircategory Emacs
  38 @direntry
  39 * Newsticker: (newsticker). A Newsticker for Emacs.
  40 @end direntry
  41
  42 @titlepage
  43 @title Newsticker -- a Newsticker for Emacs
  44 @subtitle for version @value{VERSION}, @value{UPDATED}
  45 @author Ulf Jasper
  46 @author @email{ulf.jasper@@web.de}
  47 @author @uref{http://de.geocities.com/ulf_jasper}
  48 @page
  49 @vskip 0pt plus 1filll
  50 @end titlepage
  51
  52 @contents
  53
  54 @ifnottex
  55 @node Top
  56 @top Newsticker
  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 * 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 Headlines consist of a title and (possibly) a small description. They
  78 are contained in RSS (RDF Site Summary) files.  Newsticker should work
  79 with all RSS files that follow the @uref{http://purl.org/rss/1.0/spec,
  80 RDF Rich Site Summary 1.0} specification. It should also work with
  81 version 2.0 as well as other/older/alternative rss formats (like
  82 0.9<something> or such). In other words: Newsticker is a ``RSS
  83 reader'' or ``RSS aggregator''.
  84
  85 Newsticker provides several commands for reading headlines, navigating
  86 through them, marking them as read/unread, hiding old headlines etc.
  87 Headlines can be displayed as plain text or as rendered HTML.
  88
  89 Headlines can be displayed in the echo area, either scrolling like
  90 messages in a stock-quote ticker, or just changing.
  91
  92 Newsticker allows for automatic processing of headlines by providing
  93 hooks and (sample) functions for automatically downloading images and
  94 enclosed files (as delivered by podcasts, e.g.).
  95
  96 @ifhtml
  97 Here are screen shots of the @uref{newsticker-1.7.png, version 1.7
  98 (current version)} and some older screen shots:
  99 @uref{newsticker-1.6.png, version 1.6},
 100 @uref{newsticker-1.5.png, version 1.5},
 101 @uref{newsticker-1.4.png, version 1.4}
 102 @uref{newsticker-1.3.png, version 1.3},
 103 @uref{newsticker-1.0.png, version 1.0}.
 104 @end ifhtml
 105
 106 @node Requirements
 107 @chapter Requirements
 108
 109 Newsticker can be used with
 110 @uref{http://www.gnu.org/software/emacs/emacs.html, GNU Emacs} version
 111 21.1 or later as well as @uref{http://www.xemacs.org, XEmacs}.  It
 112 requires an XML-parser (@file{xml.el}) which is part of GNU Emacs.  If
 113 you are using XEmacs you want to get the @file{net-utils} package
 114 which contains @file{xml.el} for XEmacs.
 115
 116 Newsticker requires a program which can retrieve files via http and
 117 prints them to stdout.  By default Newsticker will use
 118 @uref{http://www.gnu.org/software/wget/wget.html, wget} for this task.
 119
 120
 121 @node Installation
 122 @chapter Installation
 123
 124 Place Newsticker in a directory where Emacs can find it. Add the
 125 following line to your Emacs startup file (@file{~/.emacs}).
 126
 127 @lisp
 128 (add-to-list 'load-path "/path/to/newsticker/")
 129 (autoload 'newsticker-start "newsticker" "Emacs Newsticker" t)
 130 (autoload 'newsticker-show-news "newsticker" "Emacs Newsticker" t)
 131 @end lisp
 132
 133 Newsticker-mode supports imenu. This allows for navigating with the
 134 help of a menu. In order to use this feature you should also add the
 135 following.
 136
 137 @lisp
 138 (add-hook 'newsticker-mode-hook 'imenu-add-menubar-index)
 139 @end lisp
 140
 141 That's it.
 142
 143 @node Usage
 144 @chapter Usage
 145
 146 @findex newsticker-show-news
 147 The command @code{newsticker-show-news} will display all available
 148 headlines in a special buffer, called @samp{*newsticker*}.  It will
 149 also start the asynchronous download of headlines.  The modeline in
 150 the @samp{*newsticker*} buffer informs whenever new headlines have
 151 arrived.  Clicking mouse-button 2 or pressing RET in this buffer on a
 152 headline will call @code{browse-url} to load the corresponding news
 153 story in your favourite web browser.
 154
 155 @findex newsticker-start-ticker
 156 @findex newsticker-stop-ticker
 157 The scrolling, or flashing of headlines in the echo area, can be
 158 started with the command @code{newsticker-start-ticker}. It can be
 159 stopped with @code{newsticker-stop-ticker}.
 160
 161 @findex newsticker-start
 162 @findex newsticker-stop
 163 If you just want to start the periodic download of headlines use the
 164 command @code{newsticker-start}. Calling @code{newsticker-stop} will
 165 stop the periodic download, but will call
 166 @code{newsticker-stop-ticker} as well.
 167
 168 @node Configuration
 169 @chapter Configuration
 170
 171 All Newsticker options are customizable, i.e. they can be changed with
 172 Emacs customization methods: Call the command
 173 @code{customize-group} and enter @samp{newsticker} for the customization
 174 group.
 175
 176 All Newsticker options have reasonable default values, so that in most
 177 cases it is not necessary to customize settings before starting Newsticker
 178 for the first time.
 179
 180 Newsticker options are organized in the following groups.
 181
 182 @itemize
 183
 184 @item
 185 @code{newsticker-feed} contains options that define which news
 186 feeds are retrieved and how this is done.
 187
 188 @itemize
 189 @item
 190 @vindex newsticker-url-list
 191 @code{newsticker-url-list} defines the list of headlines which are
 192 retrieved.
 193 @item
 194 @vindex newsticker-retrieval-interval
 195 @code{newsticker-retrieval-interval} defines how often headlines
 196 are retrieved.
 197 @end itemize
 198
 199 @item
 200 @code{newsticker-headline-processing} contains options that define
 201 how the retrieved headlines are processed.
 202
 203 @itemize
 204 @item
 205 @vindex newsticker-keep-obsolete-items
 206 @code{newsticker-keep-obsolete-items} decides whether unread
 207 headlines that have been removed from the feed are kept in the
 208 Newsticker cache.
 209 @end itemize
 210
 211 @item
 212 @code{newsticker-layout} contains options that define how the
 213 buffer for reading RSS headlines is formatted.
 214
 215 @itemize
 216 @item
 217 @vindex newsticker-heading-format
 218 @code{newsticker-item-format} defines how the title of a headline
 219 is formatted.
 220 @end itemize
 221
 222 @item
 223 @code{newsticker-ticker} contains options that define how headlines
 224 are shown in the echo area.
 225
 226 @itemize
 227 @item
 228 @vindex newsticker-display-interval
 229 @vindex newsticker-scroll-smoothly
 230 @code{newsticker-display-interval} and
 231 @code{newsticker-scroll-smoothly} define how headlines are shown in
 232 the echo area.
 233 @end itemize
 234
 235 @item
 236 @code{newsticker-hooks} contains options for hooking other Emacs
 237 commands to newsticker functions.
 238 @itemize
 239 @item
 240 @vindex newsticker-new-item-functions
 241 @code{newsticker-new-item-functions} allows for automatic
 242 processing of headlines. See `newsticker-download-images', and
 243 `newsticker-download-enclosures' for sample functions.
 244 @end itemize
 245
 246 @item
 247 @code{newsticker-miscellaneous} contains other Newsticker options.
 248
 249 @end itemize
 250
 251 Please have a look at the customization buffers for the complete list
 252 of options.
 253
 254 @node Remarks
 255 @chapter Remarks
 256
 257 This newsticker is designed do its job silently in the background
 258 without disturbing you.  However, it is probably impossible to prevent
 259 such a tool from slightly attenuating your Editor's responsiveness
 260 every once in a while.
 261
 262 Byte-compiling newsticker.el is recommended.
 263
 264
 265
 266 @node Index
 267 @unnumbered Index
 268
 269 @printindex cp
 270
 271 @bye
 272
 273
 274
 275 @ignore
 276    arch-tag: 7a4de539-117c-4658-b799-0b9e3d0ccec0
 277 @end ignore