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