| 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, 2005, 2006, 2007, 2008, 2009 |
| 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.3 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 | |
| 27 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
| 28 | modify this GNU manual. Buying copies from the FSF supports it in |
| 29 | developing GNU and promoting software freedom.'' |
| 30 | @end quotation |
| 31 | @end copying |
| 32 | |
| 33 | @dircategory Emacs |
| 34 | @direntry |
| 35 | * Newsticker: (newsticker). A Newsticker for Emacs. |
| 36 | @end direntry |
| 37 | |
| 38 | @titlepage |
| 39 | @title Newsticker -- a Newsticker for Emacs |
| 40 | @subtitle for version @value{VERSION}, @value{UPDATED} |
| 41 | @author Ulf Jasper |
| 42 | @author @email{ulf.jasper@@web.de} |
| 43 | @author @uref{http://ulf.epplejasper.de/} |
| 44 | @page |
| 45 | @vskip 0pt plus 1filll |
| 46 | @insertcopying |
| 47 | @end titlepage |
| 48 | |
| 49 | @contents |
| 50 | |
| 51 | @ifnottex |
| 52 | @node Top |
| 53 | @top Newsticker |
| 54 | |
| 55 | @insertcopying |
| 56 | |
| 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 | * GNU Free Documentation License:: The license for this documentation. |
| 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 | works 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'', ``Feed |
| 98 | aggregator'', or ``Feed reader''. |
| 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 retrieves headlines either via Emacs' built-in retrieval |
| 132 | functions, by an arbitrary external program that retrieves files via |
| 133 | http and prints them to stdout (like |
| 134 | @uref{http://www.gnu.org/software/wget/wget.html, wget}, or -- on a |
| 135 | per feed basis -- via an arbitrary Lisp command. |
| 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. It will also start the asynchronous download of headlines. |
| 160 | |
| 161 | You can choose between two different frontends for reading headlines: |
| 162 | @itemize |
| 163 | @item Newsticker's @emph{treeview} uses separate windows for the |
| 164 | feeds (in tree form), a list of headlines for the current feed, and |
| 165 | the content of the current headline. Feeds can be placed into groups |
| 166 | which itself can be placed in groups and so on. |
| 167 | @item Newsticker's @emph{plainview} displays all headlines in a |
| 168 | single buffer, called @samp{*newsticker*}. The modeline in the |
| 169 | @samp{*newsticker*} buffer informs whenever new headlines have |
| 170 | arrived. |
| 171 | @end itemize |
| 172 | In both views clicking mouse-button 2 or pressing RET on a headline |
| 173 | will call @code{browse-url} to load the corresponding news story in |
| 174 | your favourite web browser. |
| 175 | |
| 176 | @findex newsticker-start-ticker |
| 177 | @findex newsticker-stop-ticker |
| 178 | The scrolling, or flashing of headlines in the echo area, can be |
| 179 | started with the command @code{newsticker-start-ticker}. It can be |
| 180 | stopped with @code{newsticker-stop-ticker}. |
| 181 | |
| 182 | @findex newsticker-start |
| 183 | @findex newsticker-stop |
| 184 | If you just want to start the periodic download of headlines use the |
| 185 | command @code{newsticker-start}. Calling @code{newsticker-stop} will |
| 186 | stop the periodic download, but will call |
| 187 | @code{newsticker-stop-ticker} as well. |
| 188 | |
| 189 | @node Configuration |
| 190 | @chapter Configuration |
| 191 | |
| 192 | All Newsticker options are customizable, i.e. they can be changed with |
| 193 | Emacs customization methods: Call the command |
| 194 | @code{customize-group} and enter @samp{newsticker} for the customization |
| 195 | group. |
| 196 | |
| 197 | All Newsticker options have reasonable default values, so that in most |
| 198 | cases it is not necessary to customize settings before starting Newsticker |
| 199 | for the first time. |
| 200 | |
| 201 | The following list shows the available groups of newsticker options |
| 202 | and some of the most important options. |
| 203 | |
| 204 | @itemize |
| 205 | |
| 206 | @item |
| 207 | @code{newsticker-retrieval} contains options that define which news |
| 208 | feeds are retrieved and how this is done. |
| 209 | |
| 210 | @itemize |
| 211 | @item |
| 212 | @vindex newsticker-url-list |
| 213 | @code{newsticker-url-list} defines the list of headlines which are |
| 214 | retrieved. |
| 215 | @item |
| 216 | @vindex newsticker-retrieval-method |
| 217 | @code{newsticker-retrieval-method} defines how headlines are |
| 218 | retrieved. This is either done using Emacs' built-in download |
| 219 | capabilities or using an external tool. |
| 220 | @item |
| 221 | @vindex newsticker-retrieval-interval |
| 222 | @code{newsticker-retrieval-interval} defines how often headlines |
| 223 | are retrieved. |
| 224 | @end itemize |
| 225 | |
| 226 | @item |
| 227 | @code{newsticker-headline-processing} contains options that define |
| 228 | how the retrieved headlines are processed. |
| 229 | |
| 230 | @itemize |
| 231 | @item |
| 232 | @vindex newsticker-keep-obsolete-items |
| 233 | @code{newsticker-keep-obsolete-items} decides whether unread |
| 234 | headlines that have been removed from the feed are kept in the |
| 235 | Newsticker cache. |
| 236 | @item |
| 237 | @vindex newsticker-auto-mark-filter-list |
| 238 | @code{newsticker-auto-mark-filter-list} provides the possibility to |
| 239 | automatically mark headlines as immortal or old. |
| 240 | @end itemize |
| 241 | |
| 242 | @item |
| 243 | @code{newsticker-hooks} contains options for hooking other Emacs |
| 244 | commands to newsticker functions. |
| 245 | @itemize |
| 246 | @item |
| 247 | @vindex newsticker-new-item-functions |
| 248 | @code{newsticker-new-item-functions} allows for automatic |
| 249 | processing of headlines. See `newsticker-download-images', and |
| 250 | `newsticker-download-enclosures' for sample functions. |
| 251 | @item |
| 252 | @vindex newsticker-plainview-hooks |
| 253 | The subgroup @code{newsticker-plainview-hooks} contains hook which |
| 254 | apply to the plainview reader only. |
| 255 | @end itemize |
| 256 | |
| 257 | @item |
| 258 | @code{newsticker-miscellaneous} contains other Newsticker options. |
| 259 | |
| 260 | @item |
| 261 | @code{newsticker-ticker} contains options that define how headlines |
| 262 | are shown in the echo area, i.e. the ``ticker''. |
| 263 | |
| 264 | @itemize |
| 265 | @item |
| 266 | @vindex newsticker-display-interval |
| 267 | @vindex newsticker-scroll-smoothly |
| 268 | @code{newsticker-ticker-interval} and |
| 269 | @code{newsticker-scroll-smoothly} define how headlines are shown in |
| 270 | the echo area. |
| 271 | @end itemize |
| 272 | |
| 273 | |
| 274 | @item |
| 275 | @code{newsticker-reader} contains options for adjusting the headline reader. |
| 276 | |
| 277 | @itemize |
| 278 | @item |
| 279 | @vindex newsticker-frontend |
| 280 | @code{newsticker-frontend} determines the actual headline reader. The |
| 281 | ``plainview'' reader uses a single buffer, the ``treeview'' uses |
| 282 | separate buffers and windows. |
| 283 | @end itemize |
| 284 | |
| 285 | @itemize |
| 286 | @item |
| 287 | @vindex newsticker-plainview |
| 288 | The subgroup @code{newsticker-plainview} contains options for the |
| 289 | plainview reader. |
| 290 | @item |
| 291 | @vindex newsticker-treeview |
| 292 | The subgroup @code{newsticker-treeview} contains options for the |
| 293 | treeview reader. |
| 294 | @end itemize |
| 295 | |
| 296 | @end itemize |
| 297 | |
| 298 | For the complete list of options please have a look at the |
| 299 | customization buffers. |
| 300 | |
| 301 | @node Remarks |
| 302 | @chapter Remarks |
| 303 | |
| 304 | Byte-compiling newsticker.el is recommended. |
| 305 | |
| 306 | @node GNU Free Documentation License |
| 307 | @appendix GNU Free Documentation License |
| 308 | @include doclicense.texi |
| 309 | |
| 310 | @node Index |
| 311 | @unnumbered Index |
| 312 | |
| 313 | @printindex cp |
| 314 | |
| 315 | @bye |
| 316 | |
| 317 | |
| 318 | |
| 319 | @ignore |
| 320 | arch-tag: 7a4de539-117c-4658-b799-0b9e3d0ccec0 |
| 321 | @end ignore |