all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
blob fec571d92334f17378e74aa934c6783840e7abf2 19163 bytes (raw)
name: doc/misc/newsticker.texi 	 # note: path name is non-authoritative(*)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
 
\input texinfo   @c -*-texinfo-*-
@comment %**start of header
@setfilename ../../info/newsticker.info
@include emacsver.texi
@set VERSION @value{EMACSVER}
@settitle Newsticker @value{VERSION}
@include docstyle.texi
@syncodeindex vr cp
@syncodeindex fn cp
@syncodeindex pg cp
@comment %**end of header

@copying
This manual documents Newsticker, a feed reader for Emacs.  It
corresponds to Emacs version @value{EMACSVER}.

@noindent
Copyright @copyright{} 2004--2022 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation License''.

(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual.''
@end quotation
@end copying

@dircategory Emacs network features
@direntry
* Newsticker: (newsticker).     A feed reader for Emacs.
@end direntry

@titlepage
@title Newsticker---a feed reader for Emacs
@author Ulf Jasper
@author @email{ulf.jasper@@web.de}
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Newsticker

@insertcopying

@end ifnottex

@menu
* Overview::             What is Newsticker?
* Installation::         Things to do before starting Newsticker the first time.
* Retrieving News::      How Newsticker fetches headlines.
* Headline Management::  How Newsticker stores headlines.
* Reading News::         How to read RSS and Atom feeds with Newsticker.
* Automatic Processing:: Automatically process news items.
* Configuration::        Customize Newsticker to your liking.
* Supported Formats::    RSS and Atom formats supported by Newsticker.

* GNU Free Documentation License:: The license for this documentation.
* Index::                          Variable, function, and concept index.
@end menu

@node Overview
@chapter Overview

Newsticker provides a @b{Feed Reader} for Emacs.  It retrieves
headlines from a list of news sites, processes them, and provides
frontends for reading and managing them. (Standard headline formats
are RSS and Atom which makes Newsticker an ``RSS Reader'', ``Atom
Reader'' or ``Feed Aggregator''.)

Headlines (or news items) consist of a title, (mostly) a description,
and a link to the full story. The description may be a brief summary
in plain text or a full HTML-formatted article.  A headline may carry
enclosed data such as images, audio or video files, typically in the
case of so ``podcast feeds''.

Newsticker downloads headlines asynchronously at configurable times,
processes and stores them so that you can read them later.  The list
of subscribed feeds, the headline processing, the presentation of the
headlines and almost all other aspects of Newsticker can be
customized to your liking.

@node Installation
@chapter Installation

As Newsticker is part of GNU Emacs there is no need to perform any
installation steps in order to use it.

Newsticker is highly customizable. All options have reasonable default
values, so that (in most cases) it is not necessary to customize
anything before you start Newsticker for the first time.

@node Retrieving News
@chapter Retrieving News

Newsticker downloads news periodically in the background.  This is
triggered as soon as you start reading news (@ref{Reading News}).

@findex newsticker-start
@findex newsticker-stop
Alternatively you may use the command @code{newsticker-start}
(@code{newsticker-stop}) in order to start (stop) the periodic
download of news without opening the reader.

The following variables define which feeds are fetched and how this is
done.

@table @code
@vindex newsticker-url-list-defaults
@item newsticker-url-list-defaults
You may select any number of feeds from this list of (sample) news feeds.

@vindex newsticker-url-list
@item newsticker-url-list
All your personal news feeds are defined here.  Each feed is
identified by its name and an URL@.  You may set the start-time and the
retrieval interval for each feed as well as the retrieval command
arguments in case that the default values do not fit a certain feed.

@vindex newsticker-retrieval-method
@vindex newsticker-wget-name
@vindex newsticker-wget-arguments
@item newsticker-retrieval-method
By default Newsticker uses Emacs's built-in download capabilities for
fetching headlines.  You may change this to use an external tool like
@code{wget}.  In this case you need to set @code{newsticker-wget-name}
and possibly @code{newsticker-wget-arguments}.

@vindex newsticker-retrieval-interval
@item newsticker-retrieval-interval
The number of seconds between headline retrievals.
@end table

@node Headline Management
@chapter Headline Management

@cindex Age
@cindex Status

Newsticker assigns a status (or ``age'') to each headline which you
can modify manually.  This makes it easy to distinguish new headlines
from old ones, to keep important headlines, to hide boring headlines
etc.  An item is ``new'' when it has just arrived and has not been
read.  You can mark it as ``old'' when you have read it or -- if you
want to keep it -- you can mark it as ``immortal''.  You can do that
manually and you can define filters which do that automatically, see
below.  When a headline has vanished from the feed it is automatically
marked as ``obsolete'' unless it has the status ``immortal''.
``Obsolete'' headlines get removed automatically after a certain time.

@table @code
@cindex Filter
@vindex newsticker-auto-mark-filter-list
@item newsticker-auto-mark-filter-list
You may define any number of filters for automatically marking newly
arrived headlines as ``immortal'' or ``old''.  A filter looks for a
regular expression in either the title or the description of a
headline and then, if the expression matches, marks the headline as
``immortal'' or as ``old''.  This is done only once, when a headline
is fetched for the very first time.

@vindex newsticker-keep-obsolete-items
@vindex newsticker-obsolete-item-max-age
@item newsticker-keep-obsolete-items
Obsolete headlines are removed immediately unless
@code{newsticker-keep-obsolete-items} is non-@code{nil} in which case they
are kept until @code{newsticker-obsolete-item-max-age} is reached.

@vindex newsticker-automatically-mark-items-as-old
@item newsticker-automatically-mark-items-as-old
If this is set to @code{t} then a ``new'' item becomes ``old'' as soon as
it is retrieved a second time.

@end table

@node Reading News
@chapter Reading News

@findex newsticker-show-news
Start Newsticker with the command @kbd{M-x newsticker-show-news}. This
will start the asynchronous news download and displays all available
headlines.

@menu
* Frontends::        Select the way headlines are displayed.
* Navigation::       Move to the next unread headline etc.
* Marking::          Mark important headlines.
* More Actions::     Add new feeds etc..
@end menu

@node Frontends
@section Frontends
@cindex Frontends

@vindex newsticker-frontend
Newsticker provides two different @i{views} for browsing, marking and
reading news.  The variable @code{newsticker-frontend} determines the
actual headline reader.

@subheading Treeview
@cindex Treeview

In this view separate windows are used for displaying feeds, headlines
and their descriptions.  The feeds are shown as a tree on the left
hand side, headlines of the currently selected feed are shown on the
upper right side, and the full contents of the currently selected
headline is shown on the lower right side.

Feeds can be placed into groups, which themselves can be placed in
groups and so on.  This results in the tree which is displayed on the
left.  A node represents either a feed or a group of feeds holding a
subtree.  The following commands allow for managing groups.

@table @kbd
@item M-a
@kindex M-a
@findex newsticker-group-add-group
Add a new feed group. Name of the new group and of the parent group
must be entered.  If The name of the parent group is the new group
becomes a top-level group. (@code{newsticker-group-add-group})
@item M-m
@kindex M-m
@findex newsticker-group-move-feed
Moves a feed into a group. The name of the group must be
entered. (@code{newsticker-group-move-feed})
@end table

The position of groups and feeds within the tree can be changed with these
commands:

@table @kbd
@item M-@key{UP}
@itemx M-@key{DOWN}
@kindex M-UP
@kindex M-DOWN
@findex newsticker-group-shift-feed-up
@findex newsticker-group-shift-feed-down
Shift the currently selected feed up and down within its group.
@item M-S-@key{UP}
@itemx M-S-@key{DOWN}
@kindex M-S-UP
@kindex M-S-DOWN
@findex newsticker-group-shift-group-up
@findex newsticker-group-shift-group-down
Shift the currently selected group up and down within its parent group.
@end table

The group settings are saved to a file either automatically when
newsticker is being quit or manually when the following command is
executed.

@table @kbd
@item s
@kindex s
@findex newsticker-treeview-save
Save treeview group settings.
@end table

The Treeview is updated automatically as soon as new headlines have
arrived.

The Treeview is used when the variable @code{newsticker-frontend} is
set to the value @code{newsticker-treeview}. (Alternatively it can be
started with the command @code{newsticker-treeview}.)

@subheading Plainview
@cindex Plainview

In this view all headlines of all feeds are displayed in a single
buffer (@file{*newsticker*}). The modeline in the @file{*newsticker*}
buffer informs you whenever new headlines have arrived.

You may want to use imenu with Plainview, which allows for navigating
with the help of a menu. In this case add the following to your Emacs
startup file (@file{~/.emacs}).

@lisp
(add-hook 'newsticker-mode-hook 'imenu-add-menubar-index)
@end lisp

(Note that preparing the Plainview takes significantly more time than
starting the Treeview because all headlines are displayed in a single
buffer.  When you have subscribed to a large amount of feeds you may
find that Newsticker's efforts of minimizing rendering times, caching
rendered items and so on  you may find However, when you have
subscribed to a large amount of feeds you may want to give the
Treeview a try.)

The Plainview is used when the variable @code{newsticker-frontend} is
set to the value @code{newsticker-plainview}. (Alternatively it can be
started with the command @code{newsticker-plainview}.)

@subheading Ticker
@cindex Ticker

Additionally, headlines can be displayed in the echo area in the style of a
news ticker.

@findex newsticker-start-ticker
@findex newsticker-stop-ticker
Headlines can be displayed in the echo area, either scrolling like
messages in a stock-quote ticker, or just changing.  This can be
started with the command @code{newsticker-start-ticker}.  It can be
stopped with @code{newsticker-stop-ticker}.


@node Navigation
@section Navigation
@cindex Navigation

Navigating through the list of feeds and headlines is rather
straightforward.  You may do this either with the mouse or with the
keyboard.  The following key bindings are provided in both, the
Treeview as well as the Plainview.

@table @kbd
@item f
@findex newsticker-next-feed
@findex newsticker-treeview-next-feed
Move to next feed (@code{newsticker-next-feed},
@code{newsticker-treeview-next-feed}).
@item F
@findex newsticker-previous-feed
@findex newsticker-treeview-prev-feed
Move to previous feed (@code{newsticker-previous-feed},
@code{newsticker-treeview-prev-feed}).
@item n
@findex newsticker-next-item
@findex newsticker-treeview-next-item
Move to next item (@code{newsticker-next-item},
@code{newsticker-treeview-next-item}).
@item N
@findex newsticker-next-new-item
@findex newsticker-treeview-next-new-item
Move to next new item (possibly in another feed)
(@code{newsticker-next-new-item},
@code{newsticker-treeview-next-new-item}).
@item p
@findex newsticker-previous-item
@findex newsticker-treeview-prev-item
Move to previous item (@code{newsticker-previous-item},
@code{newsticker-treeview-prev-item}).
@item P
@findex newsticker-previous-new-item
@findex newsticker-treeview-prev-new-item
Move to previous new item (possibly in another feed)
(@code{newsticker-previous-new-item},
@code{newsticker-treeview-prev-new-item}).
@end table

@subheading Treeview
@table @kbd
@item j
@findex newsticker-treeview-jump
Enter the name of a feed and jump to it
(@code{newsticker-treeview-jump}).
@end table


@node Marking
@section Marking
@cindex Marking

The following key bindings are provided in both, the Treeview as well
as the Plainview.

@table @kbd
@item o
@findex newsticker-mark-item-at-point-as-read
@findex newsticker-treeview-mark-item-old
Mark current item as old.
(@code{newsticker-mark-item-at-point-as-read},
@code{newsticker-treeview-mark-item-old}).
@item i
@findex newsticker-mark-item-at-point-as-immortal
@findex newsticker-treeview-mark-item-immortal
Mark current item as immortal.  Immortal items are kept forever.
(@code{newsticker-mark-item-at-point-as-immortal},
@code{newsticker-treeview-mark-item-immortal}).
@end table

@node More Actions
@section More Actions
@cindex More Actions

@subheading View full article
@table @kbd
@cindex Get News
@item v
@itemx @key{RET}
@itemx mouse-1
@findex newsticker-treeview-browse-url
Open the link to the full article (as contained in the current
headline) in your web browser @code{newsticker-treeview-browse-url}).
@end table

@subheading Get News
@cindex Get News

You can force immediate download of news with the following commands.

@table @kbd
@item g
@findex newsticker-treeview-get-news
Get news for currently shown feed (@code{newsticker-treeview-get-news}).
@item G
@findex newsticker-get-all-news
Get news for all feeds (@code{newsticker-get-all-news}).
@end table

@subheading Add More Feeds
@cindex Add More Feeds

@table @kbd
@item a
@findex newsticker-add-url
The command @code{newsticker-add-url} prompts for an URL and a name of
a new feed.  It then prepares a customization buffer where the details
of the new feed can be set.
@end table


@node Automatic Processing
@chapter Automatic Processing
@cindex Automatic Processing

Apart from automatic marking of headlines (by means of filters)
Newsticker provides the possibility to fully process newly arrived
headlines.  Instead of reading headlines yourself you can tell
Newsticker to do that for you.

@vindex newsticker-new-item-functions
In order to do so write a function which takes two arguments

@table @var
@item FEEDNAME
the name of the corresponding news feed,
@item ITEM
the decoded headline.
@end table

and add it to @code{newsticker-new-item-functions}.  Each function
contained in this list is called once for each new headline.
Depending on the feed name and the contents of the new headline you
can

@itemize
@item
automatically download images referenced in HTML-formatted
descriptions (for which a function already exists, see
@code{newsticker-download-images}),
@item
automatically save enclosed audio and video files (for which another
function exists as well, see @code{newsticker-download-enclosures}),
@item
flash the screen while playing some sound,
@item
whatever you want.
@end itemize

@node Configuration
@chapter Configuration

All Newsticker options are customizable, i.e., they can be changed with
Emacs customization methods.  Call the command
@code{customize-group} and enter @samp{newsticker} for the customization
group.

@noindent
The following list shows the available groups of Newsticker options
and some of the most important options.

@itemize

@item
@code{newsticker-retrieval} contains options that define which news
feeds are retrieved and how this is done.

@itemize
@item
@vindex newsticker-url-list
@code{newsticker-url-list} defines the list of headlines that are
retrieved.
@item
@vindex newsticker-retrieval-method
@code{newsticker-retrieval-method} defines how headlines are
retrieved.  This is either done using Emacs's built-in download
capabilities or using an external tool.
@item
@vindex newsticker-retrieval-interval
@code{newsticker-retrieval-interval} defines how often headlines
are retrieved.
@end itemize

@item
@code{newsticker-headline-processing} contains options that define
how the retrieved headlines are processed.

@itemize
@item
@vindex newsticker-keep-obsolete-items
@code{newsticker-keep-obsolete-items} decides whether unread
headlines that have been removed from the feed are kept in the
Newsticker cache.
@item
@vindex newsticker-auto-mark-filter-list
@code{newsticker-auto-mark-filter-list} provides the possibility to
automatically mark headlines as immortal or old.
@end itemize

@item
@code{newsticker-hooks} contains options for hooking other Emacs
commands to newsticker functions.
@itemize
@item
@vindex newsticker-new-item-functions
@code{newsticker-new-item-functions} allows for automatic
processing of headlines.  See @code{newsticker-download-images}, and
@code{newsticker-download-enclosures} for sample functions.
@item
@vindex newsticker-plainview-hooks
The subgroup @code{newsticker-plainview-hooks} contains hooks that
apply to the plainview reader only.
@end itemize

@item
@code{newsticker-miscellaneous} contains other Newsticker options.

@item
@code{newsticker-ticker} contains options that define how headlines
are shown in the echo area, i.e., the ``ticker''.

@itemize
@item
@vindex newsticker-display-interval
@vindex newsticker-scroll-smoothly
@code{newsticker-ticker-interval} and
@code{newsticker-scroll-smoothly} define how headlines are shown in
the echo area.
@end itemize


@item
@code{newsticker-reader} contains options for adjusting the headline reader.

@itemize
@item
@vindex newsticker-frontend
@code{newsticker-frontend} determines the actual headline reader.  The
``plainview'' reader uses a single buffer, the ``treeview'' uses
separate buffers and windows.
@end itemize

@itemize
@item
@vindex newsticker-plainview
The subgroup @code{newsticker-plainview} contains options for the
plainview reader.
@item
@vindex newsticker-treeview
The subgroup @code{newsticker-treeview} contains options for the
treeview reader.
@end itemize

@end itemize

@noindent
For the complete list of options please have a look at the
customization buffers.

@node Supported Formats
@appendix Supported Formats
@cindex Supported Formats

Newsticker works with the standard RSS and Atom formats listed below
(being lenient with feeds which break the specifications).

@subheading RSS formats

@itemize
@item RSS 0.91 (see @uref{http://backend.userland.com/rss091})
@item RSS 0.92 (see @uref{http://backend.userland.com/rss092})
@item RSS 1.0 (see @uref{http://web.resource.org/rss/1.0/spec})
@item RSS 2.0 (see @uref{https://cyber.harvard.edu/rss/rss.html})
@end itemize

@subheading Atom formats

@itemize
@item Atom 0.3
@item Atom 1.0 (see
@uref{https://datatracker.ietf.org/doc/rfc4287/})
@end itemize


@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi

@node Index
@unnumbered Index
@printindex cp


@bye

debug log:

solving fec571d923 ...
found fec571d923 in https://git.savannah.gnu.org/cgit/emacs.git

(*) Git path names are given by the tree(s) the blob belongs to.
    Blobs themselves have no identifier aside from the hash of its contents.^

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.