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 | |
c6ab4664 | 10 | @documentencoding UTF-8 |
4009494e GM |
11 | @comment %**end of header |
12 | ||
13 | @copying | |
14 | This manual is for Newsticker (version @value{VERSION}, @value{UPDATED}). | |
15 | ||
16 | @noindent | |
6bc383b1 | 17 | Copyright @copyright{} 2004--2014 Free Software Foundation, Inc. |
4009494e GM |
18 | |
19 | @quotation | |
20 | Permission is granted to copy, distribute and/or modify this document | |
6a2c4aec | 21 | under the terms of the GNU Free Documentation License, Version 1.3 or |
4009494e GM |
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 | 27 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
6bf430d1 | 28 | modify this GNU manual.'' |
4009494e GM |
29 | @end quotation |
30 | @end copying | |
31 | ||
0c973505 | 32 | @dircategory Emacs network features |
4009494e | 33 | @direntry |
62e034c2 | 34 | * Newsticker: (newsticker). A Newsticker for Emacs. |
4009494e GM |
35 | @end direntry |
36 | ||
37 | @titlepage | |
f99f1641 | 38 | @title Newsticker---a Newsticker for Emacs |
4009494e GM |
39 | @subtitle for version @value{VERSION}, @value{UPDATED} |
40 | @author Ulf Jasper | |
41 | @author @email{ulf.jasper@@web.de} | |
47bcb4d3 | 42 | @author @uref{http://ulf.epplejasper.de/} |
4009494e GM |
43 | @page |
44 | @vskip 0pt plus 1filll | |
45 | @insertcopying | |
46 | @end titlepage | |
47 | ||
48 | @contents | |
49 | ||
50 | @ifnottex | |
51 | @node Top | |
52 | @top Newsticker | |
5dc584b5 | 53 | |
c5e87d10 | 54 | @insertcopying |
5dc584b5 | 55 | |
4009494e GM |
56 | @end ifnottex |
57 | ||
58 | @menu | |
59 | * Overview:: General description of newsticker. | |
60 | * Requirements:: Requirements for using newsticker. | |
61 | * Installation:: Installing newsticker on your system. | |
62 | * Usage:: Basic newsticker instructions. | |
63 | * Configuration:: Customizable newsticker settings. | |
64 | * Remarks:: Remarks about newsticker. | |
65 | * GNU Free Documentation License:: The license for this documentation. | |
66 | * Index:: Variable, function, and concept index. | |
67 | @end menu | |
68 | ||
69 | @node Overview | |
70 | @chapter Overview | |
71 | ||
d259be38 | 72 | Newsticker provides a newsticker for Emacs. A newsticker is a thing |
4009494e GM |
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 | ||
78 | Headlines consist of a title and (possibly) a small description. They | |
d259be38 | 79 | are contained in ``RSS'' (RDF Site Summary) or ``Atom'' files. Newsticker |
47bcb4d3 | 80 | works with the following RSS formats: |
4009494e GM |
81 | |
82 | @itemize | |
83 | @item RSS 0.91 (see @uref{http://backend.userland.com/rss091} or | |
84 | @uref{http://my.netscape.com/publish/formats/rss-spec-0.91.html}), | |
85 | @item RSS 0.92 (see @uref{http://backend.userland.com/rss092}), | |
86 | @item RSS 1.0 (see @uref{http://purl.org/rss/1.0/spec} | |
87 | @item RSS 2.0 (see @uref{http://blogs.law.harvard.edu/tech/rss}), | |
88 | @end itemize | |
89 | @itemize | |
90 | as well as the following Atom formats: | |
91 | @item Atom 0.3 | |
92 | @item Atom 1.0 (see | |
9d7a25d6 | 93 | @uref{https://datatracker.ietf.org/doc/rfc4287/}). |
4009494e GM |
94 | @end itemize |
95 | ||
47bcb4d3 UJ |
96 | That makes Newsticker.el an ``Atom aggregator'', ``RSS reader'', ``Feed |
97 | aggregator'', or ``Feed reader''. | |
4009494e GM |
98 | |
99 | Newsticker provides several commands for reading headlines, navigating | |
100 | through them, marking them as read/unread, hiding old headlines etc. | |
101 | Headlines can be displayed as plain text or as rendered HTML. | |
102 | ||
103 | Headlines can be displayed in the echo area, either scrolling like | |
104 | messages in a stock-quote ticker, or just changing. | |
105 | ||
106 | Newsticker allows for automatic processing of headlines by providing | |
107 | hooks and (sample) functions for automatically downloading images and | |
d259be38 | 108 | enclosed files (as delivered by, e.g., podcasts). |
4009494e | 109 | |
d259be38 | 110 | @ignore |
4009494e GM |
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}, | |
c5e87d10 | 115 | @uref{newsticker-1.5.png, version 1.5}, |
4009494e | 116 | @uref{newsticker-1.4.png, version 1.4} |
c5e87d10 | 117 | @uref{newsticker-1.3.png, version 1.3}, |
4009494e GM |
118 | @uref{newsticker-1.0.png, version 1.0}. |
119 | @end ifhtml | |
d259be38 | 120 | @end ignore |
4009494e GM |
121 | |
122 | @node Requirements | |
123 | @chapter Requirements | |
124 | ||
125 | Newsticker can be used with | |
126 | @uref{http://www.gnu.org/software/emacs/emacs.html, GNU Emacs} version | |
127 | 21.1 or later as well as @uref{http://www.xemacs.org, XEmacs}. It | |
d259be38 | 128 | requires an XML-parser (@file{xml.el}), which is part of GNU Emacs. If |
4009494e GM |
129 | you are using XEmacs you want to get the @file{net-utils} package |
130 | which contains @file{xml.el} for XEmacs. | |
131 | ||
44e97401 | 132 | Newsticker retrieves headlines either via Emacs's built-in retrieval |
47bcb4d3 UJ |
133 | functions, by an arbitrary external program that retrieves files via |
134 | http and prints them to stdout (like | |
f99f1641 PE |
135 | @uref{http://www.gnu.org/software/wget/wget.html, wget}, or---on a |
136 | per feed basis---via an arbitrary Lisp command. | |
4009494e GM |
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 | |
47bcb4d3 UJ |
160 | headlines. It will also start the asynchronous download of headlines. |
161 | ||
162 | You can choose between two different frontends for reading headlines: | |
163 | @itemize | |
164 | @item Newsticker's @emph{treeview} uses separate windows for the | |
165 | feeds (in tree form), a list of headlines for the current feed, and | |
d259be38 GM |
166 | the content of the current headline. Feeds can be placed into groups, |
167 | which themselves can be placed in groups and so on. | |
47bcb4d3 | 168 | @item Newsticker's @emph{plainview} displays all headlines in a |
d29fbf47 GM |
169 | single buffer, called @file{*newsticker*}. The modeline in the |
170 | @file{*newsticker*} buffer informs you whenever new headlines have | |
47bcb4d3 UJ |
171 | arrived. |
172 | @end itemize | |
98374c9a XF |
173 | In both views clicking mouse-button 2 or pressing @key{RET} on a |
174 | headline will call @code{browse-url} to load the corresponding news | |
175 | story in your favorite web browser. | |
4009494e GM |
176 | |
177 | @findex newsticker-start-ticker | |
178 | @findex newsticker-stop-ticker | |
179 | The scrolling, or flashing of headlines in the echo area, can be | |
d259be38 | 180 | started with the command @code{newsticker-start-ticker}. It can be |
4009494e GM |
181 | stopped with @code{newsticker-stop-ticker}. |
182 | ||
183 | @findex newsticker-start | |
184 | @findex newsticker-stop | |
185 | If you just want to start the periodic download of headlines use the | |
d259be38 | 186 | command @code{newsticker-start}. Calling @code{newsticker-stop} will |
4009494e GM |
187 | stop the periodic download, but will call |
188 | @code{newsticker-stop-ticker} as well. | |
189 | ||
190 | @node Configuration | |
191 | @chapter Configuration | |
192 | ||
1df7defd | 193 | All Newsticker options are customizable, i.e., they can be changed with |
d259be38 | 194 | Emacs customization methods. Call the command |
4009494e GM |
195 | @code{customize-group} and enter @samp{newsticker} for the customization |
196 | group. | |
197 | ||
198 | All Newsticker options have reasonable default values, so that in most | |
199 | cases it is not necessary to customize settings before starting Newsticker | |
200 | for the first time. | |
201 | ||
47bcb4d3 UJ |
202 | The following list shows the available groups of newsticker options |
203 | and some of the most important options. | |
4009494e GM |
204 | |
205 | @itemize | |
206 | ||
207 | @item | |
47bcb4d3 | 208 | @code{newsticker-retrieval} contains options that define which news |
c5e87d10 | 209 | feeds are retrieved and how this is done. |
4009494e GM |
210 | |
211 | @itemize | |
212 | @item | |
213 | @vindex newsticker-url-list | |
d259be38 | 214 | @code{newsticker-url-list} defines the list of headlines that are |
4009494e GM |
215 | retrieved. |
216 | @item | |
47bcb4d3 UJ |
217 | @vindex newsticker-retrieval-method |
218 | @code{newsticker-retrieval-method} defines how headlines are | |
44e97401 | 219 | retrieved. This is either done using Emacs's built-in download |
47bcb4d3 UJ |
220 | capabilities or using an external tool. |
221 | @item | |
4009494e GM |
222 | @vindex newsticker-retrieval-interval |
223 | @code{newsticker-retrieval-interval} defines how often headlines | |
224 | are retrieved. | |
225 | @end itemize | |
226 | ||
227 | @item | |
228 | @code{newsticker-headline-processing} contains options that define | |
229 | how the retrieved headlines are processed. | |
230 | ||
231 | @itemize | |
232 | @item | |
233 | @vindex newsticker-keep-obsolete-items | |
234 | @code{newsticker-keep-obsolete-items} decides whether unread | |
235 | headlines that have been removed from the feed are kept in the | |
236 | Newsticker cache. | |
47bcb4d3 UJ |
237 | @item |
238 | @vindex newsticker-auto-mark-filter-list | |
239 | @code{newsticker-auto-mark-filter-list} provides the possibility to | |
240 | automatically mark headlines as immortal or old. | |
4009494e GM |
241 | @end itemize |
242 | ||
243 | @item | |
47bcb4d3 | 244 | @code{newsticker-hooks} contains options for hooking other Emacs |
c5e87d10 | 245 | commands to newsticker functions. |
4009494e GM |
246 | @itemize |
247 | @item | |
47bcb4d3 UJ |
248 | @vindex newsticker-new-item-functions |
249 | @code{newsticker-new-item-functions} allows for automatic | |
d259be38 GM |
250 | processing of headlines. See @code{newsticker-download-images}, and |
251 | @code{newsticker-download-enclosures} for sample functions. | |
47bcb4d3 UJ |
252 | @item |
253 | @vindex newsticker-plainview-hooks | |
d259be38 | 254 | The subgroup @code{newsticker-plainview-hooks} contains hooks that |
47bcb4d3 | 255 | apply to the plainview reader only. |
4009494e GM |
256 | @end itemize |
257 | ||
47bcb4d3 UJ |
258 | @item |
259 | @code{newsticker-miscellaneous} contains other Newsticker options. | |
260 | ||
4009494e GM |
261 | @item |
262 | @code{newsticker-ticker} contains options that define how headlines | |
1df7defd | 263 | are shown in the echo area, i.e., the ``ticker''. |
4009494e GM |
264 | |
265 | @itemize | |
266 | @item | |
267 | @vindex newsticker-display-interval | |
268 | @vindex newsticker-scroll-smoothly | |
47bcb4d3 | 269 | @code{newsticker-ticker-interval} and |
4009494e GM |
270 | @code{newsticker-scroll-smoothly} define how headlines are shown in |
271 | the echo area. | |
272 | @end itemize | |
273 | ||
47bcb4d3 | 274 | |
4009494e | 275 | @item |
47bcb4d3 UJ |
276 | @code{newsticker-reader} contains options for adjusting the headline reader. |
277 | ||
4009494e GM |
278 | @itemize |
279 | @item | |
47bcb4d3 | 280 | @vindex newsticker-frontend |
d259be38 | 281 | @code{newsticker-frontend} determines the actual headline reader. The |
47bcb4d3 UJ |
282 | ``plainview'' reader uses a single buffer, the ``treeview'' uses |
283 | separate buffers and windows. | |
4009494e GM |
284 | @end itemize |
285 | ||
47bcb4d3 | 286 | @itemize |
4009494e | 287 | @item |
47bcb4d3 UJ |
288 | @vindex newsticker-plainview |
289 | The subgroup @code{newsticker-plainview} contains options for the | |
290 | plainview reader. | |
291 | @item | |
292 | @vindex newsticker-treeview | |
293 | The subgroup @code{newsticker-treeview} contains options for the | |
294 | treeview reader. | |
295 | @end itemize | |
4009494e GM |
296 | |
297 | @end itemize | |
298 | ||
47bcb4d3 UJ |
299 | For the complete list of options please have a look at the |
300 | customization buffers. | |
4009494e GM |
301 | |
302 | @node Remarks | |
303 | @chapter Remarks | |
304 | ||
4009494e GM |
305 | Byte-compiling newsticker.el is recommended. |
306 | ||
307 | @node GNU Free Documentation License | |
308 | @appendix GNU Free Documentation License | |
309 | @include doclicense.texi | |
310 | ||
311 | @node Index | |
312 | @unnumbered Index | |
313 | ||
314 | @printindex cp | |
315 | ||
316 | @bye |