Commit | Line | Data |
---|---|---|
4009494e GM |
1 | \input texinfo @c -*-texinfo-*- |
2 | @comment %**start of header | |
db78a8cb | 3 | @setfilename ../../info/newsticker |
47bcb4d3 UJ |
4 | @set VERSION 1.99 |
5 | @set UPDATED June 2008 | |
4009494e GM |
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 | |
6f093307 GM |
16 | Copyright @copyright{} 2004, 2005, 2006, 2007, 2008 |
17 | Free Software Foundation, Inc. | |
4009494e GM |
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 | |
debf4439 | 25 | is included in the section entitled ``GNU Free Documentation License''. |
4009494e | 26 | |
6f093307 GM |
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.'' | |
4009494e GM |
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} | |
47bcb4d3 | 43 | @author @uref{http://ulf.epplejasper.de/} |
4009494e GM |
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 | @end ifnottex | |
55 | ||
56 | @menu | |
57 | * Overview:: General description of newsticker. | |
58 | * Requirements:: Requirements for using newsticker. | |
59 | * Installation:: Installing newsticker on your system. | |
60 | * Usage:: Basic newsticker instructions. | |
61 | * Configuration:: Customizable newsticker settings. | |
62 | * Remarks:: Remarks about newsticker. | |
63 | * GNU Free Documentation License:: The license for this documentation. | |
64 | * Index:: Variable, function, and concept index. | |
65 | @end menu | |
66 | ||
67 | @node Overview | |
68 | @chapter Overview | |
69 | ||
70 | Newsticker provides a newsticker for Emacs. A newsticker is a thing | |
71 | that asynchronously retrieves headlines from a list of news sites, | |
72 | prepares these headlines for reading, and allows for loading the | |
73 | corresponding articles in a web browser. | |
74 | ||
75 | ||
76 | Headlines consist of a title and (possibly) a small description. They | |
77 | are contained in "RSS" (RDF Site Summary) or "Atom" files. Newsticker | |
47bcb4d3 | 78 | works with the following RSS formats: |
4009494e GM |
79 | |
80 | @itemize | |
81 | @item RSS 0.91 (see @uref{http://backend.userland.com/rss091} or | |
82 | @uref{http://my.netscape.com/publish/formats/rss-spec-0.91.html}), | |
83 | @item RSS 0.92 (see @uref{http://backend.userland.com/rss092}), | |
84 | @item RSS 1.0 (see @uref{http://purl.org/rss/1.0/spec} | |
85 | @item RSS 2.0 (see @uref{http://blogs.law.harvard.edu/tech/rss}), | |
86 | @end itemize | |
87 | @itemize | |
88 | as well as the following Atom formats: | |
89 | @item Atom 0.3 | |
90 | @item Atom 1.0 (see | |
91 | @uref{http://www.ietf.org/internet-drafts/draft-ietf-atompub-format-11.txt}). | |
92 | @end itemize | |
93 | ||
47bcb4d3 UJ |
94 | That makes Newsticker.el an ``Atom aggregator'', ``RSS reader'', ``Feed |
95 | aggregator'', or ``Feed reader''. | |
4009494e GM |
96 | |
97 | Newsticker provides several commands for reading headlines, navigating | |
98 | through them, marking them as read/unread, hiding old headlines etc. | |
99 | Headlines can be displayed as plain text or as rendered HTML. | |
100 | ||
101 | Headlines can be displayed in the echo area, either scrolling like | |
102 | messages in a stock-quote ticker, or just changing. | |
103 | ||
104 | Newsticker allows for automatic processing of headlines by providing | |
105 | hooks and (sample) functions for automatically downloading images and | |
106 | enclosed files (as delivered by podcasts, e.g.). | |
107 | ||
108 | @ifhtml | |
109 | Here are screen shots of the @uref{newsticker-1.7.png, version 1.7 | |
110 | (current version)} and some older screen shots: | |
111 | @uref{newsticker-1.6.png, version 1.6}, | |
112 | @uref{newsticker-1.5.png, version 1.5}, | |
113 | @uref{newsticker-1.4.png, version 1.4} | |
114 | @uref{newsticker-1.3.png, version 1.3}, | |
115 | @uref{newsticker-1.0.png, version 1.0}. | |
116 | @end ifhtml | |
117 | ||
118 | @node Requirements | |
119 | @chapter Requirements | |
120 | ||
121 | Newsticker can be used with | |
122 | @uref{http://www.gnu.org/software/emacs/emacs.html, GNU Emacs} version | |
123 | 21.1 or later as well as @uref{http://www.xemacs.org, XEmacs}. It | |
124 | requires an XML-parser (@file{xml.el}) which is part of GNU Emacs. If | |
125 | you are using XEmacs you want to get the @file{net-utils} package | |
126 | which contains @file{xml.el} for XEmacs. | |
127 | ||
47bcb4d3 UJ |
128 | Newsticker retrieves headlines either via Emacs' built-in retrieval |
129 | functions, by an arbitrary external program that retrieves files via | |
130 | http and prints them to stdout (like | |
131 | @uref{http://www.gnu.org/software/wget/wget.html, wget}, or -- on a | |
132 | per feed basis -- via an arbitrary Lisp command. | |
4009494e GM |
133 | |
134 | ||
135 | @node Installation | |
136 | @chapter Installation | |
137 | ||
138 | As Newsticker is part of GNU Emacs there is no need to perform any | |
139 | installation steps in order to use Newsticker. | |
140 | ||
141 | However, if you are using imenu, which allows for navigating with the | |
142 | help of a menu, you should add the following to your Emacs startup file | |
143 | (@file{~/.emacs}). | |
144 | ||
145 | @lisp | |
146 | (add-hook 'newsticker-mode-hook 'imenu-add-menubar-index) | |
147 | @end lisp | |
148 | ||
149 | That's it. | |
150 | ||
151 | @node Usage | |
152 | @chapter Usage | |
153 | ||
154 | @findex newsticker-show-news | |
155 | The command @code{newsticker-show-news} will display all available | |
47bcb4d3 UJ |
156 | headlines. It will also start the asynchronous download of headlines. |
157 | ||
158 | You can choose between two different frontends for reading headlines: | |
159 | @itemize | |
160 | @item Newsticker's @emph{treeview} uses separate windows for the | |
161 | feeds (in tree form), a list of headlines for the current feed, and | |
162 | the content of the current headline. Feeds can be placed into groups | |
163 | which itself can be placed in groups and so on. | |
164 | @item Newsticker's @emph{plainview} displays all headlines in a | |
165 | single buffer, called @samp{*newsticker*}. The modeline in the | |
166 | @samp{*newsticker*} buffer informs whenever new headlines have | |
167 | arrived. | |
168 | @end itemize | |
169 | In both views clicking mouse-button 2 or pressing RET on a headline | |
170 | will call @code{browse-url} to load the corresponding news story in | |
171 | your favourite web browser. | |
4009494e GM |
172 | |
173 | @findex newsticker-start-ticker | |
174 | @findex newsticker-stop-ticker | |
175 | The scrolling, or flashing of headlines in the echo area, can be | |
176 | started with the command @code{newsticker-start-ticker}. It can be | |
177 | stopped with @code{newsticker-stop-ticker}. | |
178 | ||
179 | @findex newsticker-start | |
180 | @findex newsticker-stop | |
181 | If you just want to start the periodic download of headlines use the | |
182 | command @code{newsticker-start}. Calling @code{newsticker-stop} will | |
183 | stop the periodic download, but will call | |
184 | @code{newsticker-stop-ticker} as well. | |
185 | ||
186 | @node Configuration | |
187 | @chapter Configuration | |
188 | ||
189 | All Newsticker options are customizable, i.e. they can be changed with | |
190 | Emacs customization methods: Call the command | |
191 | @code{customize-group} and enter @samp{newsticker} for the customization | |
192 | group. | |
193 | ||
194 | All Newsticker options have reasonable default values, so that in most | |
195 | cases it is not necessary to customize settings before starting Newsticker | |
196 | for the first time. | |
197 | ||
47bcb4d3 UJ |
198 | The following list shows the available groups of newsticker options |
199 | and some of the most important options. | |
4009494e GM |
200 | |
201 | @itemize | |
202 | ||
203 | @item | |
47bcb4d3 | 204 | @code{newsticker-retrieval} contains options that define which news |
4009494e GM |
205 | feeds are retrieved and how this is done. |
206 | ||
207 | @itemize | |
208 | @item | |
209 | @vindex newsticker-url-list | |
210 | @code{newsticker-url-list} defines the list of headlines which are | |
211 | retrieved. | |
212 | @item | |
47bcb4d3 UJ |
213 | @vindex newsticker-retrieval-method |
214 | @code{newsticker-retrieval-method} defines how headlines are | |
215 | retrieved. This is either done using Emacs' built-in download | |
216 | capabilities or using an external tool. | |
217 | @item | |
4009494e GM |
218 | @vindex newsticker-retrieval-interval |
219 | @code{newsticker-retrieval-interval} defines how often headlines | |
220 | are retrieved. | |
221 | @end itemize | |
222 | ||
223 | @item | |
224 | @code{newsticker-headline-processing} contains options that define | |
225 | how the retrieved headlines are processed. | |
226 | ||
227 | @itemize | |
228 | @item | |
229 | @vindex newsticker-keep-obsolete-items | |
230 | @code{newsticker-keep-obsolete-items} decides whether unread | |
231 | headlines that have been removed from the feed are kept in the | |
232 | Newsticker cache. | |
47bcb4d3 UJ |
233 | @item |
234 | @vindex newsticker-auto-mark-filter-list | |
235 | @code{newsticker-auto-mark-filter-list} provides the possibility to | |
236 | automatically mark headlines as immortal or old. | |
4009494e GM |
237 | @end itemize |
238 | ||
239 | @item | |
47bcb4d3 UJ |
240 | @code{newsticker-hooks} contains options for hooking other Emacs |
241 | commands to newsticker functions. | |
4009494e GM |
242 | @itemize |
243 | @item | |
47bcb4d3 UJ |
244 | @vindex newsticker-new-item-functions |
245 | @code{newsticker-new-item-functions} allows for automatic | |
246 | processing of headlines. See `newsticker-download-images', and | |
247 | `newsticker-download-enclosures' for sample functions. | |
248 | @item | |
249 | @vindex newsticker-plainview-hooks | |
250 | The subgroup @code{newsticker-plainview-hooks} contains hook which | |
251 | apply to the plainview reader only. | |
4009494e GM |
252 | @end itemize |
253 | ||
47bcb4d3 UJ |
254 | @item |
255 | @code{newsticker-miscellaneous} contains other Newsticker options. | |
256 | ||
4009494e GM |
257 | @item |
258 | @code{newsticker-ticker} contains options that define how headlines | |
47bcb4d3 | 259 | are shown in the echo area, i.e. the ``ticker''. |
4009494e GM |
260 | |
261 | @itemize | |
262 | @item | |
263 | @vindex newsticker-display-interval | |
264 | @vindex newsticker-scroll-smoothly | |
47bcb4d3 | 265 | @code{newsticker-ticker-interval} and |
4009494e GM |
266 | @code{newsticker-scroll-smoothly} define how headlines are shown in |
267 | the echo area. | |
268 | @end itemize | |
269 | ||
47bcb4d3 | 270 | |
4009494e | 271 | @item |
47bcb4d3 UJ |
272 | @code{newsticker-reader} contains options for adjusting the headline reader. |
273 | ||
4009494e GM |
274 | @itemize |
275 | @item | |
47bcb4d3 UJ |
276 | @vindex newsticker-frontend |
277 | @code{newsticker-frontend} determines the actual headline reader. The | |
278 | ``plainview'' reader uses a single buffer, the ``treeview'' uses | |
279 | separate buffers and windows. | |
4009494e GM |
280 | @end itemize |
281 | ||
47bcb4d3 | 282 | @itemize |
4009494e | 283 | @item |
47bcb4d3 UJ |
284 | @vindex newsticker-plainview |
285 | The subgroup @code{newsticker-plainview} contains options for the | |
286 | plainview reader. | |
287 | @item | |
288 | @vindex newsticker-treeview | |
289 | The subgroup @code{newsticker-treeview} contains options for the | |
290 | treeview reader. | |
291 | @end itemize | |
4009494e GM |
292 | |
293 | @end itemize | |
294 | ||
47bcb4d3 UJ |
295 | For the complete list of options please have a look at the |
296 | customization buffers. | |
4009494e GM |
297 | |
298 | @node Remarks | |
299 | @chapter Remarks | |
300 | ||
4009494e GM |
301 | Byte-compiling newsticker.el is recommended. |
302 | ||
303 | @node GNU Free Documentation License | |
304 | @appendix GNU Free Documentation License | |
305 | @include doclicense.texi | |
306 | ||
307 | @node Index | |
308 | @unnumbered Index | |
309 | ||
310 | @printindex cp | |
311 | ||
312 | @bye | |
313 | ||
314 | ||
315 | ||
316 | @ignore | |
317 | arch-tag: 7a4de539-117c-4658-b799-0b9e3d0ccec0 | |
318 | @end ignore |