This repository has been archived by the owner on Oct 10, 2019. It is now read-only.
/
newsbeuter.txt
1038 lines (807 loc) · 42.3 KB
/
newsbeuter.txt
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
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
The Newsbeuter RSS Feedreader
=============================
Andreas Krennmair <ak@newsbeuter.org>
Introduction
------------
Newsbeuter is an RSS feedreader. RSS is a number of widely-used XML formats to
transmit, publish and syndicate articles, for example news or blog articles.
Newsbeuter is designed to be used on text terminals on Unix or Unix-like
systems such as Linux, FreeBSD or Mac OS X.
Platforms
~~~~~~~~~
Newsbeuter has been tested on Linux, FreeBSD and Mac OS X, and is available in
the form of pre-built packages for many popular Linux distributions. For a current
list of distributions with newsbeuter packages, consult http://www.newsbeuter.org/download.html[this list on the newsbeuter website].
OpenBSD is currently unsupported, as it lacks even the most basic support for
internationalization and localization.
NetBSD is currently not supported, due to technical limitations in the iconv()
implementation.
Why "Newsbeuter"?
~~~~~~~~~~~~~~~~
"Newsbeuter" is a pun on the German word "Wildbeuter", which means
"hunter-gatherer". During the stone age, people hunted and gathered their food,
and these days, they hunt and gather news and information. Credits for this
idea goes to Clifford Wolf, who submitted it to a little competition that was
started when I got aware that the original name would violate French and
European registered trademarks.
Installation
------------
This chapter describes how to compile and install newsbeuter from source.
Downloading Newsbeuter
~~~~~~~~~~~~~~~~~~~~~~
Newsbeuter is available as source package. Simply go to
http://www.newsbeuter.org/[] and download the latest source package, which is
usually in the .tar.gz file format. Alternatively, you can check out the latest
development source tree from the newsbeuter Git repository (hosted on GitHub)
by running the following command on the commandline:
git clone git://github.com/akrennmair/newsbeuter.git
Dependencies
~~~~~~~~~~~~
Newsbeuter depends on a number of libraries to function correctly. This table
lists these dependencies. Please be aware that the list libraries may
themselves depend on other libraries. These dependencies are not listed here.
Please also be aware that you need a recent C++ compiler. Currently, newsbeuter
has only been tested with GCC.
- STFL (version 0.21 or newer): http://www.clifford.at/stfl/[]
- SQLite 3 (version 3.5 or newer): http://www.sqlite.org/[]
- libcurl: http://curl.haxx.se/download.html[]
- GNU gettext (on systems that don't provide gettext in the libc): ftp://ftp.gnu.org/gnu/gettext/[]
- pkg-config: http://pkg-config.freedesktop.org/wiki/[]
- libxml2: http://xmlsoft.org/[]
If you intend to modify and regenerate the filter language parser, you will also
need Coco/R for C++, which you can download from
http://www.ssw.uni-linz.ac.at/coco/[]. The Coco/R binary must be installed as
"cococpp" in your PATH. Debian users only need to install the package
"coco-cpp". Use the "regenerate-parser" make target to regenerate the necessary
files.
Compiling and Installing
~~~~~~~~~~~~~~~~~~~~~~~~
After you've downloaded and installed the dependencies mentioned above, you can
start compiling and installing newsbeuter. To compile newsbeuter, simply run
"make" in the source tree. After a short time, this should complete
successfully, and you can go on with installation by running "make install". By
default, this will install the "newsbeuter" binary to the /usr/local/bin
directory. You can provide an alternative installation path using the prefix
parameter, e.g. running "make install prefix=/opt/newsbeuter" will install the
binary to the directory /opt/newsbeuter/bin.
First Steps
-----------
include::chapter-firststeps.txt[]
.Configuration Commands
[frame="all", grid="all",format="dsv",separator="|"]
`10`15`15`40`20~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Configuration Command|Argument(s)|Default|Description|Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
include::configcommands.dsv[]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.Available Operations
[frame="all", grid="all", format="dsv",separator=":"]
`20`20`60~~~~~~~~~~~~~~~~~~~~~~~~
Operation:Default key:Description
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
include::keycmds.dsv[]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Keys, as used in the bind-key configuration command, use a special syntax.
Lowercase keys, uppercase keys and special characters are written literally.
The Enter key is written as "ENTER", while the Esc key is written as "ESC". The
function keys F1 to F12 are written as "F1" to "F12". The Space key is written
as "SPACE". Key combinations with the Ctrl key, such as Ctrl-R, are written as
^R. Please be aware that all Ctrl-related key combinations need to be written
in uppercase. The following identifiers for keys are supported:
- ENTER (Enter key)
- BACKSPACE (backspace key)
- LEFT (left cursor)
- RIGHT (right cursor)
- UP (up cursor)
- PPAGE (page up cursor)
- NPAGE (page down cursor)
- DOWN (down cursor)
- ESC (Esc key)
The "Tab" key can't be bound due to technical limitations of STFL.
Example Configuration
~~~~~~~~~~~~~~~~~~~~~
# a comment
max-items 100 # such comments are possible, too
browser links
show-read-feeds no
unbind-key R
bind-key ^R reload-all
Configuring Colors
~~~~~~~~~~~~~~~~~~
It is possible to configure custom color settings in newsbeuter. The basic configuration
syntax is:
color <element> <foreground color> <background color> [<attribute> ...]
This means that if you configure colors for a certain element, you need to provide
a foreground color and a background color as a minimum. The following colors are
supported:
- black
- red
- green
- yellow
- blue
- magenta
- cyan
- white
- default
- color<n>, e.g. color123
The "default" color means that the terminal's default color will be used. The
"color<n>" color name can be used if your terminal support 256 colors (e.g.
gnome-terminal, xterm with $TERM set to xterm-256color). Newsbeuter contains
support for 256 color terminals since version 2.1. For a complete chart of
colors and their corresponding numbers, please see
http://www.calmar.ws/vim/256-xterm-24bit-rgb-color-chart.html[].
Optionally, you can also add one or more attributes. The following attributes are
supported:
- standout
- underline
- reverse
- blink
- dim
- bold
- protect
- invis
Currently, the following elements are supported:
- *listnormal*: a normal list item
- *listfocus*: the currently selected list item
- *info*: the info bars on top and bottom
- *background*: the application background
- *article*: the article text
The default color configuration of newsbeuter looks like this:
background white black
listnormal white black
listfocus yellow blue bold
info yellow blue bold
article white black
Migrating from other RSS Feed Readers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is very likely that you have used other RSS feed readers before. In this
case, it is practical to migrate the previous configuration to newsbeuter. The
vast amount of RSS feed readers allows the export of subscriptions via OPML
files. OPML is an XML file format that was designed to save outlines, and has
found its primary use in the import and export of feed subscriptions between
different RSS feed readers.
The best thing to start with is to export your subscriptions from the old
reader. Usually, RSS feed readers have appropriate menu items available to do
so.
Snownews provides a script to convert your current subscription file into an
OPML file:
snow2opml > ~/blogroll.opml
This command creates from your Snownews configuration a file blogroll.opml in
your home directory. To export the subscription list from raggle, the
following command is necessary:
raggle --export-opml ~/blogroll.opml
When you have exported the subscriptions from your old RSS feed reader, you can
import them into newsbeuter:
newsbeuter -i ~/blogroll.opml
Don't worry, newsbeuter won't destroy your existing configuration, or add
subscriptions more than once: every URL that is added to the subscription list
is checked before whether it is already in the list, and is only added if not.
This makes it possible to merge several OPML files into your subscription list.
If your old RSS feed reader was able to structure your subscriptions in
hierarchies, and reflected this structure in the exported OPML file, newsbeuter
doesn't throw away this information (although it doesn't support hierarchies), but
generates tags from it. Tags are newsbeuter's way of organizing subscriptions
in a non-hierarchical way. More information on the use of tags can be found below.
Imagine the following folder hierarchy:
|- News
| |- Europe
| `- International
|- IT
| |- Linux
| |- Windows
| `- Programming
| |- C++
| |- Ruby
| `- Erlang
`- Private
Subscriptions found in the folder "Private" will be tagged with "Private",
subscriptions in the folder "International" will be tagged with "News" and
"News/International", subscriptions in the folder "Erlang" will be tagged ith
"IT", "IT/Programming" and "IT/Programming/Erlang", and so on. This means that
when you select the tag "Programming" in newsbeuter, you will see all
subscriptions that were in the "Programming" folder or one of its subfolders
before. This means that you will lose virtually nothing of your previously
configured structure.
Advanced Features
-----------------
Tagging
~~~~~~~
include::chapter-tagging.txt[]
Scripts and Filters (Snownews Extensions)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
include::chapter-snownews.txt[]
Bookmarking
~~~~~~~~~~~
Since version 0.7, newsbeuter contains a plugin-based bookmarking system. When a user bookmarks a link (possible
in the article list, in the article view, and in the URL view), he is asked for the URL to bookmark (already
preset with the URL of the current selection), the bookmark title (in most cases preset with the
title of the current selection) and the bookmark description. After the question for the description, an
external program, configured via the configuration command "bookmark-cmd", is executed with 3 commandline
parameters. The plugin itself implements the actual bookmark saving (e.g. writing the bookmark to an
external file, or storing it to a del.icio.us account). When everything went OK, the plugin simply exits.
In case something goes wrong while saving the bookmark, it writes out an error message as a single line.
This error message is then presented to the user from within newsbeuter.
Newsbeuter comes with an example plugin, which implements a simple tab-separated bookmark file. This
example can be found in the "doc" subdirectory.
Command Line
~~~~~~~~~~~~
include::chapter-cmdline.txt[]
.Available Commandline Commands
[frame="all", grid="all", format="dsv"]
`20`20`40`20~~~~~~~~~~~~~~~~~~~
Command:Syntax:Description:Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
quit:quit:Quit newsbeuter.:quit
save:save <filename>:Save the currently select article to disk. This works in the article list and in the article view.:save ~/important.txt
set:set <variable>[=<value>|&|!]:Set configuration variable <variable> to <value>. If no value is specified, the current value is printed out. Specifying a '!' after the name of boolean configuration variables toggles their values, a '&' directly after the name of a configuration variable of any type resets its value to the documented default value.:set reload-time=15
tag:tag <tagname>:Only display feeds with the tag <tagname>.:tag news
goto:goto <case-insensitive substring>:Go to the next feed whose name contains the case-insensitive substring.:goto foo
source:source <filename> [...]:Load the specified configuration files. This allows it to load alternative configuration files or reload already loaded configuration files on-the-fly from the filesystem.:source ~/.newsbeuter/colors
dumpconfig:dumpconfig <filename>:Save current internal state of configuration to file, so that it can be instantly reused as configuration file.:dumpconfig ~/.newsbeuter/config.saved
dumpform:dumpform:Dump current dialog to text file. This is meant for debugging purposes only.:dumpform
n/a:<number>:Jump to the entry with the index <number> (usually seen at the left side of the list). This currently works for the feed list and the article list.:30
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Filter Language
~~~~~~~~~~~~~~~
Newsbeuter provides a powerful filter language that enables the user to
filter the content of many dialogs, such as the feed list or the article
list. The basic concept is that every feed and every article has a
number of attributes which can then be compared with user-supplied
values, and these comparisons and be logically AND'ed, OR'ed and
grouped.
Examples for simple filter expressions are:
unread_count > 0
rssurl =~ "^https:"
age between 0:10
Logically connecting and grouping such expressions looks like in the
following examples:
( unread_count > 0 and unread_count < 10 ) or total_count > 100
( author =~ "Frank" or author =~ "John" ) and ( title =~ "Linux" or title =~ "FreeBSD" )
The possibilities for combining such queries is endless, sky (actually:
the available memory) is the limit.
To filter your feeds, press "F" in the feed list, enter your filter expression,
and press enter. To clear the filter, press Ctrl-F. To filter the articles in the article list,
press "F", enter your expression, and press enter. Clearing the filter works the same as before.
Be aware that only certain attributes work in both dialogs. The table below lists all available
attributes and their context, i.e. an attribute that belongs to a feed can only be matched
in the feed list, while an attribute that belongs to an article can only be matched in the
article list.
.Available Comparison Operators
[frame="all", grid="all", format="dsv"]
`30`70~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Operator:Meaning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=:test for equality ("==" works, too)
!=:test for inequality; logical negation of = operator
=~:test whether regular expression matches
!~:logical negation of the =~ operator
<:less than
>:greater than
<=:less than or equal
>=:greater than or equal
between:within a range of integer values, where the two integer values are separated by a colon (see above for an example)
#:contains; this operator matches if a word is contained in a list of space-separated words (useful for matching tags, see below)
!#:contains not; the negation of the # operator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.Available Attributes
[frame="all", grid="all", format="dsv"]
`30`30`40~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Attribute:Context:Meaning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
title:article:article title
link:article:article link
author:article:article author
content:article:article body
date:article:publication date of the article
guid:article:a unique identifier of the article
unread:article:indicates whether the article has been read
enclosure_url:article:the URL of a possible enclosure (e.g. podcast file)
enclosure_type:article:the MIME type of the enclosure URL
flags:article:The set of flags of the article
age:article:Age of an article (in days)
articleindex:article:Index of an article in an article list
feedtitle:feed, article:title of the feed
description:feed, article:feed description
feedlink:feed, article:link to the feed
feeddate:feed, article:publication date of the feed
rssurl:feed, article:RSS URL of the feed
unread_count:feed, article:number of unread articles in the feed
total_count:feed, article:total number of articles in the feed
tags:feed, article:all tags that are associated with the feed
feedindex:feed, article:Index of a feed in the feed list
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Note that it's also possible to filter for feed attributes when you query for
article attributes. This is because every article is internally linked to the
feed from which it was downloaded.
Killfiles
~~~~~~~~~
Sometimes, a user is confronted with certain content he doesn't want to read,
e.g. on topics the user is not interested in or articles from certain people he
doesn't want to read. In Usenet, such functionality within software is
traditionally called a "killfile", i.e. based on the content of this "killfile",
articles that match certain conditions do not get displayed and are not presented
to the user at all.
In newsbeuter, such a "killfile" can be implemented on a per-article basis via
the configuration file. The most important configuration command for this
is "ignore-article":
ignore-article "*" "title =~ \"Gentoo\""
ignore-article "http://synflood.at/blog/index.php?/feeds/index.rss2" "title =~ \"newsbeuter\""
The basic format is that the user specifies an RSS feed for which the ignore
shall be applied ("*" matches all RSS feeds), and then a filter expression (see
previous section). If newsbeuter hits an article in the specified RSS feed that
matches the specified filter expression, then this article is ignored and never
presented to the user. The configuration itself can contain as many
ignore-article commands as desired.
Since newsbeuter 2.2, you can specify the way an article is ignored. There are
two ways available:
- During download: articles are ignored when a feed is downloaded and parsed,
and thus won't be written to the local cache.
- During display: articles are downloaded and written to the local cache, but
are ignored when a feed is displayed.
Both modes have their advantages and disadvantages: while the download ignore
mode saves some storage, you cannot simply "undo" the ignore by removing it
from the configuration file: if an ignored article has already vanished from a
feed, it won't reappear. On the other hand, the display ignore mode requires
some more space, but has the advantage that an ignore can be "undone" by
removing the ignore-article configuration command from the configuration.
The default ignore mode is "download". You can set the ignore mode in the
configuration file:
ignore-mode "display"
Query Feeds
~~~~~~~~~~~
Query feeds are a mechanism of newsbeuter to define custom "meta feeds" by using
newsbeuter's built-in filter language. A query feed is a feed that is aggregated
from all currently downloaded articles of all feeds. To narrow down the set of
articles, the user has to specify a filter. Only articles that match this filter
are added to the query feed. A query feed is updated whenever it is entered in
the feed list. When you change the unread flag of an article, this is reflected
in the feed where the article was originally fetched.
To define a query feed, the user has to add a line to the file
~/.newsbeuter/urls in the following format:
query:<name of feed>:<filter expression> [<tag> ...]
The "query:" in the beginning tells newsbeuter that it's a query feed, "<name of
feed>" specifies the name under which the query feed shall be displayed in the
feed list, and "<filter expression>" is the filter expression that shall be
used. Like every other feed, a query feed can be tagged to organize it like
a regular feed.
A good example for the user of this feature is a query feed that contains all
unread articles:
"query:Unread Articles:unread = \"yes\""
Note the quotes that are necessary around the complete query "URL" and the
backslashes that are necessary the escape the quotes in the filter expression.
If you want to combine several feeds to one single feed, a good solution is to
tag the feeds that you want to combine with one certain tag, and then create a
query feed that only displays articles from feeds with that certain tag:
http://domain1.tld/feed.xml fun news tag1
http://domain2.tld/?feed.rss private jokes tag1
http://domain3.tld/feeds.rss news
"query:tag1 Articles:tags # \"tag1\""
In this example, the feeds http://domain1.tld/feed.xml and
http://domain2.tld/?feed.rss are aggregated into the query feed named "tag1
Articles", but the feed http://domain3.tld/feeds.rss is not.
Basically, the possibility of what can be realized with query feeds is only
limited by what can be queried from articles and feeds with the filter language
and by your creativity.
Google Reader Support
~~~~~~~~~~~~~~~~~~~~~
http://www.google.com/reader/[Google Reader] is Google's web-based feed
aggregator. Newsbeuter provides functionality to use Google Reader as its
backend: people can use Google Reader to manage their subscriptions, and in
addition, use newsbeuter to download and read articles. Newsbeuter will keep
the information which articles have already been read synchronized with Google
Reader, so that users usually won't see articles more than once. In addition, it
will only ever download unread articles from Google Reader.
In order to use Google Reader support, you first need to configure the proper URL source:
urls-source "googlereader"
In addition, newsbeuter needs to know your Google Reader username and password
so that it can authenticate with Google Reader:
googlereader-login "your-googlereader-account"
googlereader-password "your-password"
After setting these configuration values, you can start newsbeuter, it will
authenticate with Google Reader and download your subscription list. If you use
"folders" in Google Reader to organize your feeds, newsbeuter will regard them
and make them available via its "tags" capability: each feed is tagged with the
name of the folder in which it resides.
When you mark single items or complete feeds as read, newsbeuter will
synchronize this information directly to Google Reader. This, of course,
includes opening articles. Toggling read articles back to "unread" is also
communicated to Google Reader.
In addition, Google Reader provides the ability to "star" and to "share"
articles. Starred articles are basically bookmarks, while shared articles are
shown to people that follow your Google Reader account. Newsbeuter allows the
use of this feature by mapping its powerful "flags" to the "star"/"unstar"
resp. "share"/"unshare" operations.
In order to use this mapping, all you need to do is to configure the flags
that shall be used:
googlereader-flag-share "a"
googlereader-flag-star "b"
After that, use these flags when you edit flags for an article, and these
articles will be starred resp. shared.
By default, newsbeuter also shows Google Reader "special feeds":
- People you follow: articles shared by people that you follow.
- Starred items: articles that you starred.
- Shared items: articles that you shared.
- Popular items: articles that are considered to be popular by Google's algorithms.
You can disable these feeds by setting the following configuration variable:
googlereader-show-special-feeds no
Bloglines Synchronization
~~~~~~~~~~~~~~~~~~~~~~~~~
Up to and including version 2.3, newsbeuter contained support for synchronization
with Bloglines. On October 1, 2010, Bloglines was discontinued, and newsbeuter's
support for Bloglines was subsequently removed.
Tiny Tiny RSS Synchronization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Since version 2.5, newsbeuter can be used to synchronize with Tiny Tiny RSS
installations. Tiny Tiny RSS is a web-based and (optionally) multi-user feed
reader. By providing the ability to use Tiny Tiny RSS as its backend, it's
possible for users to manage their subscriptions centrally within Tiny Tiny RSS
while reading them wherever they are using newsbeuter.
If you want to use Tiny Tiny RSS support, don't forget to activate the external
API support in your preferences.
To use Tiny Tiny RSS support, you need to configure a few things. First of all,
newsbeuter needs to know that you want to use Tiny Tiny RSS and which
installation exactly:
urls-source "ttrss"
ttrss-url "http://example.com/ttrss/"
In addition, it requires username and password for authentication:
ttrss-login "myusername"
ttrss-password "mypassword"
Tiny Tiny RSS provides two modes of usage, single-user mode and multi-user
mode. newsbeuter needs to know about this, too: In single-user mode,
authentication is done via Basic HTTP authentication, while in multi-user mode,
authentication is done against Tiny Tiny RSS itself.
ttrss-mode "single" # "multi" is default
With these settings, newsbeuter should be able to connect to Tiny Tiny RSS and
download your subscribed feeds. Articles or even complete feeds that you marked
as read are synchronized directly to Tiny Tiny RSS.
Tiny Tiny RSS provides the ability to "star" and to "publish" articles. Starred
articles are basically bookmarks, while published articles can be retrieved via
a pubic RSS feed. Newsbeuter allows the use of these features by mapping its
flags to the "star" and "publish" operations.
In order to use this mapping, you need to configure the flags that shall be used:
ttrss-flag-star "s"
ttrss-flag-publish "p"
After that, use these flags when you edit flags for an article, and these articles
will be starred resp. published.
OPML Online Subscription Mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The OPML online subscription mode works similar to the Google Reader
synchronization mode, except that no information about read articles is
synchronized back. When enabled, all feeds that are listed in the feed list
will be taken from one or more OPML files that are downloaded from a freely
configurable URL.
To enable this mode, the following configuration needs to be done:
urls-source "opml"
opml-url "<opml url>" ["<opml url>" ...]
"opml" must be specified as source for the feed URLs, and the URLs of the OPML
file needs to be specified, too. As with Google Reader synchronization mode, the offline
mode via "newsbeuter -o" also works with OPML online subscription mode.
Flagging Articles
~~~~~~~~~~~~~~~~~
To support custom categorization of articles by the user, it is possible to
flag an article. A valid flag is any character from 'A' to 'Z' and from 'a' to
'z'. Every article can be flagged with up to 52 different flags, i.e. every
letter from the Roman alphabet in upper and lower case. Flagging is easy: just
select an article in the article list, or enter the article view, and press ^E.
This will start the flag editor. By pressing enter, the new flags are saved.
You can cancel by pressing the ESC key.
The flags of an article can be used in every filter expression. The flags of an
article are always ordered, and when new flags are added, ordering is
immediately restored. This behaviour can also be relied upon when querying
articles via the filter language.
If an article contains one or more flags, it is marked with an "!" in the
article list. In the article view, all flags (if available) are listed.
Macro Support
~~~~~~~~~~~~~
In newsbeuter, it's possible to define macros to execute more than one command
at once. A macro is configured using the "macro" configuration command. The
first parameter to "macro" is the key, all parameters afterwards are operations
(as listed in the "Available Operations" table above), optionally with
parameters on their own, separated by the ";" character. Here's a simple
example:
macro k open ; reload ; quit
macro o open-in-browser ; toggle-article-read "read"
When the user presses the macro prefix ("," by default) and then the "k" key,
the three operations "open", "reload" and "quit" will be executed subsequently.
It is also possible to modify configuration variables within macros, which can
e.g. be used to temporarily modify the browser configuration variable to do
something else, such as running an image viewer from the URLs view:
macro i set browser "feh %u"; open ; set browser "elinks %u"
You can even use this feature to enqueue any of the URLs from the URLs view to
podbeuter's download queue:
macro E set browser "echo %u >> ~/.newsbeuter/queue" ; open ; set browser "elinks %u"
Commandline Commands
~~~~~~~~~~~~~~~~~~~~
Newsbeuter comes with a -x option that indicates that commands added as arguments
to the command line shall be executed. Currently, the following commands are
available:
- reload: this option reloads all feeds, and quits newsbeuter without printing any output.
This is useful if a user wants to periodically reload all feeds without always having
a running newsbeuter instance, e.g. from cron.
- print-unread: this option prints the number of unread articles and quits newsbeuter.
This is useful for users who want to integrate this number into some kind of monitoring
system.
Format Strings
~~~~~~~~~~~~~~
Newsbeuter contains a powerful format string system to make it possible for the
user to configure the format of various aspects of the application, such as
the format of entries in the feed list or in the article list.
Format strings are similar to those that are found in the "printf" function in
the C programming language. A format sequence begins with the '%' character,
followed by optional alignment indication: positive numbers indicate that the
text that is inserted for the sequence shall be padded right to a total width
that is specified by the number, while negative number specify left padding.
Followed by the padding indication comes the actual sequence identifier, which
is usually a single letter.
In addition, newsbeuter provides other, more powerful sequences, such as
"%>[char]", which indicates that the text right to the sequence will be aligned
right on the screen, and characters between the text on the left and the text
on the right will be filled by "[char]". Another powerful format is the
conditional sequence, "%?[char]?[format 1]&[format 2]?": if the text of the
sequence identifier "[char]" is non-empty, then "[format 1]" will be evaluated
and inserted, otherwise "[format 2]" will be evaluated and inserted. The "&" and
"[format 2]" are optional, i.e. if the identifier's text is empty, then an
empty string will be inserted.
The following tables show what sequence identifiers are available for which
format:
.Available Identifiers for feedlist-format
[frame="all", grid="all", format="dsv"]
`30`60~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Identifier:Meaning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d:Feed description
i:Feed index
l:Feed link
L:Feed RSS URL
n:"unread" flag field
S:download status
t:Feed title
T:First tag of a feed in the URLs file
u:"unread/total" field
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
While a reload-all operation is running, the download status indicates the
download status of a feed, which can be "to be downloaded" (indicated by "_"),
"currently downloading" (indicated by "."), successfully downloaded (indicated
by " ") and "download error" (indicated by "x").
.Available Identifiers for articlelist-format
[frame="all", grid="all", format="dsv"]
`30`60~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Identifier:Meaning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a:Article author
D:Publication date
f:Article flags
i:Article index
t:Article title
T:If the article list displays articles from different feeds, then this identifier contains the title of the feed to which the article belongs.
L:Article length
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.Available Identifiers for notify-format
[frame="all", grid="all", format="dsv"]
`30`60~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Identifier:Meaning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
n:Number of unread articles
f:Number of unread feeds
d:Number of new unread articles (i.e. that were added through the last reload)
D:Number of new unread feeds (i.e. that were added through the last reload)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Examples:
feedlist-format "%4i %n %11u %t"
articlelist-format "%4i %f %D %?T?|%-17T| ?%t"
notify-format "%d new articles (%n unread articles, %f unread feeds)"
Dialog Titles
^^^^^^^^^^^^^
Starting with newsbeuter 2.0, it is now officially supported to customize
the title format of all available dialogs. Here is a list of dialogs with their
respective title format configuration variables, and a list of available formats
and their meaning. Please note taht the title formats are localized, so if you
work on a different locale that is supported by newsbeuter, the actually displayed
title text may vary unless you customize it.
.Dialog Title Formats
[frame="all", grid="all", format="dsv"]
`20`30`50~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Dialog:Configuration Variable:Default Value
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Feed List:feedlist-title-format:%N %V - Your feeds (%u unread, %t total)%?T? - tag `%T'&?
Article List:articlelist-title-format:%N %V - Articles in feed '%T' (%u unread, %t total) - %U
Search Result:searchresult-title-format:%N %V - Search result (%u unread, %t total)
File Browser:filebrowser-title-format:%N %V - %?O?Open File&Save File? - %f
Help:help-title-format:%N %V - Help
Select Tag Dialog:selecttag-title-format:%N %V - Select Tag
Select Filter Dialog:selectfilter-title-format:%N %V - Select Filter
Article View:itemview-title-format:%N %V - Article '%T'
URL View:urlview-title-format:%N %V - URLs
Dialog List:dialogs-title-format:%N %V - Dialogs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.Common Title Format Identifiers
[frame="all", grid="all", format="dsv"]
`30`60~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Identifier:Meaning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
N:Name of the program, i.e. "newsbeuter"
V:Program version
u:Number of unread articles (if applicable)
t:Number of total articles (if applicable)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.Feed List Title Format Identifiers
[frame="all", grid="all", format="dsv"]
`30`60~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Identifier:Meaning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
T:Currently selected tag (empty if none selected)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.Article List Title Format Identifiers
[frame="all", grid="all", format="dsv"]
`30`60~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Identifier:Meaning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
T:Feed title
U:Feed URL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.File Browser Title Format Identifiers
[frame="all", grid="all", format="dsv"]
`30`60~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Identifier:Meaning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
f:Filename
O:Non-empty if file browser is in open mode, empty if in save mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.Article View Title Format Identifiers
[frame="all", grid="all", format="dsv"]
`30`60~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Identifier:Meaning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
T:Article title
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Highlighting Text
~~~~~~~~~~~~~~~~~
Since version 1.0, newsbeuter supports the highlighting of text in the feed
list, the article list and the article view, using regular expressions to
describe patterns to be highlighted. The command syntax goes like this:
highlight <target> <regex> <fgcolor> [<bgcolor> [<attribute> ...]]
Valid values for <target> are "feedlist", "articlelist", "article" and "all".
When specifying "all", the matching will be done in all three views. The
<regex> must be regular expression, which will be matched case-insensitive
against the text. <fgcolor> and <bgcolor> specify the foreground color resp.
the background color of the matches. You can also specify 0 or more attributes.
You can find a list of valid colors and attributes in the "Configuring Colors"
section.
Examples for possible highlighting configurations are:
highlight all "newsbeuter" red
highlight article "^(Feed|Title|Author|Link|Date):" default default underline
highlight feedlist "https?://[^ ]+" yellow red bold
Highlighting Articles in the Article List
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In addition to generally highlighting text, there is also a specific way to
highlight articles in the article list based on whether they match a certain
filter expression. This means that you can highlight items in the article list
based on their content. This is done using the "highlight-article" configuration
command.
The syntax is similar to the "highlight" configuration command, with the difference
that there's no need to specify a target (since it only applies in the article list),
and instead of a regular expression, a filter expression is used. After the filter
expression, the colors and attributes are specified in the same way.
Example:
highlight-article "author =~ \"Andreas Krennmair\"" white red bold
Advanced Dialog Management
~~~~~~~~~~~~~~~~~~~~~~~~~~
Since version 2.0, newsbeuter supports an advanced concept of dialogs.
Previously, all dialogs (feed list, article list, article view) were internally
laid out as a pure stack. In 2.0, this changed: all dialogs are managed in a
list, and the user can jump to another, previously opened dialog from
everywhere. This allows a user to open more than one article list, more than one
article view, etc., and switch between them without closing them.
The main dialog for this feature can be reached by pressing the "v" key. This
opens the list of open dialogs. From there, the user can switch to another
dialog by selecting the appropriate entry and pressing "ENTER", or can close
open dialogs by selecting them and pressing Ctrl-X.
XDG Base Directory Support
~~~~~~~~~~~~~~~~~~~~~~~~~~
Newsbeuter implements limited support for the
http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html[XDG Base
Directory Specification]. It needs to be set up manually by creating the
following directories:
~/.local/share/newsbeuter/
~/.config/newsbeuter/
If these directories exist or the environment variables $XDG_CONFIG_HOME and
$XDG_DATA_HOME are set, newsbeuter will use these directories, otherwise it
will default to ~/.newsbeuter as its configuration directory.
Podcast Support
~~~~~~~~~~~~~~~
include::chapter-podcasts.txt[]
.Podbeuter Configuration Commands
[frame="all", grid="all",format="dsv",separator="|"]
`10`15`15`40`20~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Configuration Command|Argument(s)|Default|Description|Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
include::podbeuter-cmds.dsv[]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.Available Operations in Podbeuter
[frame="all", grid="all", format="dsv"]
`20`20`60~~~~~~~~~~~~~~~~~~~~~~~~
Operation:Default key:Description
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
quit:q:Quit the program.
pb-download:d:Download the currently selected URL.
pb-cancel:c:Cancel the currently selected download.
pb-play:p:Start player with currently selected download.
pb-delete:D:Delete the currently selected URL from the queue.
pb-purge:P:Remove all finished and deleted downloads from the queue and load URLs that were newly added to the queue.
pb-toggle-download-all:a:Toggle the "automatic download" feature where all queued URLs are downloaded one after the other. The "max-downloads" configuration option controls how many downloads are done in parallel.
pb-increase-max-dls:+:Increase the "max-downloads" option by 1.
pb-decrease-max-dls:-:Decrease the "max-downloads" option by 1. If the option is already 1, no further decrease is possible.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A usual "use case" is to configure newsbeuter to automatically enqueue newly
found podcast download URLs. Then, the user reloads the podcast RSS feeds in
newsbeuter, and after that, he/she uses podbeuter to view the current queue, and
either selectively download certain files or automatically download them all
together by pressing "a" within podbeuter.
Using SQLite Triggers with newsbeuter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section was kindly provided by mailto:elrond+newsbeuter(at)samba-tng.org[Elrond].
SQLite, the db used by newsbeuter, supports triggers. These are small
snippets of SQL that get executed inside the database by the database
engine. They're stored inside the db and the normal user (including
newsbeuter itself) doesn't see them. Just the db seems to do some magic:
Like changing some values when you change another value.
So what is this good for when looking at newsbeuter? Well first of it's a
hack. The real answer should be to use application logic (do it inside
newsbeuter, not in the db). So: Don't use this, unless you know, what you're
doing, and unless you have some sort of backup.
Example
^^^^^^^
So after the "don't use it" you still want to know, what one can do? So here's an example.
Suppose you have a strange feed where the articles become "new" by just
changing their subject, and nothing else changes. The body is just empty, and
the URL keeps the same. This feed really exists. It's the "updated software rss
feed" of some major company and the title just contains the name of the driver
and version number. And the URL points to the download page. newsbeuter
considers articles only as new, when they have a new UniqueID (this is good).
So those articles are never marked as new (unread) ever again.
So what can we do? We do some magic: We let the db test if newsbeuter
changes the subject and then let itself mark the article again as unread.
1. You need the sqlite3 command line tool (available via apt-get install sqlite3 on Debian) or some other tool to do direct sql on the sqlite database.
2. Start sqlite3 with the newsbeuter db:
Rivendell:~/.newsbeuter% sqlite3 cache.db
SQLite version 3.4.2
Enter ".help" for instructions
sqlite>
3. Create the trigger:
sqlite> create trigger update_item_title update of title on rss_item
> for each row when old.title != new.title
> begin
> update rss_item set unread = 1 where rowid == new.rowid;
> end;
4. Leave sqlite3 with <Ctrl-D> or .quit.
That's it. newsbeuter (well, its db) now marks articles as unread when their
title changes. And nicely enough this works all inside newsbeuter, no need to