Mercurial > emacs
annotate doc/misc/newsticker.texi @ 104078:2658bfb08516
Better docstring for `called-interactively-p'.
author | Bastien Guerry <bzg@altern.org> |
---|---|
date | Mon, 27 Jul 2009 02:02:49 +0000 |
parents | 9bcea07061a8 |
children | 1d1d5d9bd884 |
rev | line source |
---|---|
84307 | 1 \input texinfo @c -*-texinfo-*- |
2 @comment %**start of header | |
84329
3d431f1997d8
(setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents:
84307
diff
changeset
|
3 @setfilename ../../info/newsticker |
95912 | 4 @set VERSION 1.99 |
5 @set UPDATED June 2008 | |
84307 | 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 | |
100974 | 16 Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009 |
95874
eafbd7a5c9be
Update Back-Cover Text as per maintain.info.
Glenn Morris <rgm@gnu.org>
parents:
87903
diff
changeset
|
17 Free Software Foundation, Inc. |
84307 | 18 |
19 @quotation | |
20 Permission is granted to copy, distribute and/or modify this document | |
99709
6de181810d0f
Relicense all texi files under FDL 1.3 or later.
Glenn Morris <rgm@gnu.org>
parents:
95937
diff
changeset
|
21 under the terms of the GNU Free Documentation License, Version 1.3 or |
84307 | 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 | |
95937
6f0fce2c3559
Remove references to external license, since doclicense is included.
Glenn Morris <rgm@gnu.org>
parents:
95912
diff
changeset
|
25 is included in the section entitled ``GNU Free Documentation License''. |
84307 | 26 |
95874
eafbd7a5c9be
Update Back-Cover Text as per maintain.info.
Glenn Morris <rgm@gnu.org>
parents:
87903
diff
changeset
|
27 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
eafbd7a5c9be
Update Back-Cover Text as per maintain.info.
Glenn Morris <rgm@gnu.org>
parents:
87903
diff
changeset
|
28 modify this GNU manual. Buying copies from the FSF supports it in |
eafbd7a5c9be
Update Back-Cover Text as per maintain.info.
Glenn Morris <rgm@gnu.org>
parents:
87903
diff
changeset
|
29 developing GNU and promoting software freedom.'' |
84307 | 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} | |
95912 | 43 @author @uref{http://ulf.epplejasper.de/} |
84307 | 44 @page |
45 @vskip 0pt plus 1filll | |
46 @insertcopying | |
47 @end titlepage | |
48 | |
49 @contents | |
50 | |
51 @ifnottex | |
52 @node Top | |
53 @top Newsticker | |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
100974
diff
changeset
|
54 |
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
100974
diff
changeset
|
55 @insertcopying |
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
100974
diff
changeset
|
56 |
84307 | 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 | |
95912 | 81 works with the following RSS formats: |
84307 | 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 | |
95912 | 97 That makes Newsticker.el an ``Atom aggregator'', ``RSS reader'', ``Feed |
98 aggregator'', or ``Feed reader''. | |
84307 | 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 | |
95912 | 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. | |
84307 | 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 | |
95912 | 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. | |
84307 | 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 | |
95912 | 201 The following list shows the available groups of newsticker options |
202 and some of the most important options. | |
84307 | 203 |
204 @itemize | |
205 | |
206 @item | |
95912 | 207 @code{newsticker-retrieval} contains options that define which news |
84307 | 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 | |
95912 | 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 | |
84307 | 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 | |
95912 | 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. | |
84307 | 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. | |
95912 | 251 @item |
252 @vindex newsticker-plainview-hooks | |
253 The subgroup @code{newsticker-plainview-hooks} contains hook which | |
254 apply to the plainview reader only. | |
84307 | 255 @end itemize |
256 | |
257 @item | |
258 @code{newsticker-miscellaneous} contains other Newsticker options. | |
259 | |
95912 | 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. | |
84307 | 271 @end itemize |
272 | |
95912 | 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. | |
84307 | 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 |