NEWSRAFT(1) | General Commands Manual | NEWSRAFT(1) |
newsraft - feed reader for terminal
newsraft [-f FILE1] [-c FILE2] [-d FILE3] [-l FILE4] [-p] [-v] [-h]
Newsraft is a small text based program for reading syndication feeds - it enables you to obtain content from many blogs and platforms and view all this via one single interface in an efficient and streamlined manner.
-f FILE
-c FILE
-d FILE
-l FILE
-p
-v
-h
To start using Newsraft you have to create a feeds file with the list of links to feeds you want to receive news from. Check out FEEDS FILE section for file syntax and valid paths.
When feeds file is ready, you can launch Newsraft. There are only 4 menus you will have to deal with: sections, feeds, items and pager. Default binds are listed in ACTIONS section.
Sections menu consists of section entries which are needed to organize feeds in groups to be able to process them in bulk. They are kind of directories for feeds. If you didn't specify any section declarations in your feeds file then you will get to the feeds menu straightaway.
Feeds menu consists of feed entries. Every feed entry contains news downloaded from one specific source which you have set in feeds file. To update a single feed you have to select it and press r. If you want to update all feeds, Ctrl-R (or ^R for short) will do this fine. From feeds menu you can get to the items menu by entering some feed.
Items menu consists of feed item entries (i. e. single pieces of news) which you get when you update feeds in the previous menu. Every feed item entry has two switchable properties - read state and importance state. Keys to change read state: d to mark read, D to mark unread, ^D to mark everything read. Keys to change importance state: f to flag important, F to flag unimportant. To view item's content you have to go to pager menu by entering selected item.
Pager menu will display some details about selected item and render its content if it was provided by feed. Usually feed item entries have a links section with one link pointing to a related web page and several links that were mentioned in the item's content. You can copy these links into your clipboard with y key and open them in your web browser with o key. To target a key action to link with a specific index you have to prefix your key with this index. For example, 5y will copy fifth link and 17o will open seventeenth link in the web browser. You can also setup custom command bindings to execute any commands with these links. Consider this config file:
With this you will be able to open any link in mpv(1) and feh(1) directly from your terminal! Isn't it awesome? It is freaking amazing!
For both sections menu and feeds menu there is a special explore mode. You can toggle it by pressing the tab key (^I). It's truly miraculous: it shows all the news in the current context (i. e. in sections menu it will show you all the news in the database, whereas in feeds menu it will show you all the news of feeds in the current feeds menu). This mode may come in handy when you want to quickly scroll through all the news without switching between sections and feeds back and forth.
And for dessert, I'll tell you about search functionality. You can type / to begin search input - enter the desired query here and press Enter. This will open an items menu with a search query applied. To make filtering go away just make an empty search (press / and Enter in series).
This file contains feed entries that Newsraft will display and process. There are 4 types of lines in feeds file.
Feed lines start with a URL. After at least one whitespace character, the name of the feed may be specified - it must be enclosed in double quotes. For example:
Generator lines start with a command enclosed in $(). These act just like feed lines but instead of fetching resources from a remote server they use the output of the specified command to obtain the content.
Section lines start with @ character. After any number of whitespace characters, the name of the section must be specified. For example:
Comment lines start with # character. These lines are completely ignored. For example:
Both feed and section lines allow you to set individual settings and binds for them. The syntax is as follows:
Settings set for feeds take precedence over the settings specified for sections. Not every setting supports individual assignment - only settings with scalable mark in SETTINGS section do.
Search precedence:
This file is used to override default settings and bindings of Newsraft. Presence of config file is totally optional and Newsraft will work without it just fine. There are 3 types of lines in config file.
Setting lines start with a setting name and end with a setting value. Available settings are listed in the SETTINGS and COLOR SETTINGS sections. Here are a couple of examples:
Binding lines start with the bind word. They define actions that are performed when certain keys are pressed. Complete list of assigned actions can be found in the ACTIONS section. Format of these lines is as follows:
There is also a way to assign command bindings. When a key with assigned command binding is pressed, the specifiers in the command are replaced with values of the corresponding entry and the command is executed. You can find which specifiers are available in the description of the menu-item-entry-format setting. Format of these lines is as follows:
Binding lines support assigning multiple actions to one key. Assigned actions must be separated with semicolon symbols, for example:
In case you want to disable some binding which was set in Newsraft by default, you can use a line according to this format:
Comment lines start with # character. These lines are completely ignored. For example:
Search precedence:
This file stores everything you download from feeds in sqlite3(1) format. Although you now know the format in which the data is stored, it is highly recommended to avoid modifying the database manually - things will break and it will be very sad.
Search precedence:
Settings with scalable mark can be set for individual feeds and sections.
reload-period (scalable, default: 0)
item-limit (scalable, default: 0)
scrolloff (default: 0)
pager-width (scalable, default: 100)
pager-centering (scalable, default: true)
update-threads-count (default: 0)
menu-feed-sorting (default: none)
menu-item-sorting (default: time-desc)
open-in-browser-command (scalable, default: ${BROWSER:-xdg-open} "%l")
copy-to-clipboard-command (default: auto)
notification-command (default: auto)
proxy (scalable, default: "")
proxy-user (scalable, default: "")
proxy-password (scalable, default: "")
global-section-name (default: Global)
item-content-format (scalable, default: <b>Feed</b>: %f<br>|<b>Title</b>: %t<br>|<b>Date</b>: %d<br>|<br>%c<br>|<br><hr>%L)
item-content-date-format (scalable, default: %a, %d %b %Y %H:%M:%S %z)
item-content-link-format (scalable, default: <b>[%i]</b>: %l<br>)
list-entry-date-format (default: %b %d)
menu-section-entry-format (default: %5.0u @ %t)
menu-feed-entry-format (default: %5.0u │ %t)
menu-item-entry-format (default: " %u │ %d │ %o")
menu-explore-item-entry-format (default: " %u │ %d │ %-28O │ %o")
sections-menu-paramount-explore (default: false)
feeds-menu-paramount-explore (default: false)
mark-item-unread-on-change (scalable, default: false)
mark-item-read-on-hover (default: false)
analyze-database-on-startup (default: true)
clean-database-on-startup (default: false)
download-timeout (scalable, default: 20)
download-speed-limit (scalable, default: 0)
status-messages-count-limit (default: 1000)
user-agent (scalable, default: auto)
OS_NAME shouldn't be a matter of privacy concern, because on most systems it contains nothing more like "Linux" or "Darwin". If you want to be sure of this, check Newsraft log to see how user-agent is set at startup.
If set to "", User-Agent header will not be sent.
respect-ttl-element (scalable, default: true)
respect-expires-header (scalable, default: true)
send-if-none-match-header (scalable, default: true)
send-if-modified-since-header (scalable, default: true)
Color settings are the same settings as above, but they take two color words (foreground and background) and optional attribute words. Available colors are default, black, red, green, yellow, blue, magenta, cyan, white and colorN (N can be a number from 0 to 255). Available attributes are bold, italic and underlined.
Color setting | Default value |
color-status-good | green default |
color-status-info | cyan default |
color-status-fail | red default |
color-list-item | default default |
color-list-item-unread | yellow default |
color-list-item-important | magenta default |
color-list-feed | default default |
color-list-feed-unread | yellow default |
color-list-section | default default |
color-list-section-unread | yellow default |
Keys | Actions |
j, KEY_DOWN, ^E | select-next |
k, KEY_UP, ^Y | select-prev |
space, ^F, KEY_NPAGE | select-next-page |
^B, KEY_PPAGE | select-prev-page |
g, KEY_HOME | select-first |
G, KEY_END | select-last |
J | jump-to-next |
K | jump-to-prev |
n | jump-to-next-unread |
N | jump-to-prev-unread |
p | jump-to-next-important |
P | jump-to-prev-important |
* | goto-feed |
, | shift-west |
. | shift-east |
< | shift-reset |
t | sort-by-time |
u | sort-by-unread |
i | sort-by-important |
a | sort-by-alphabet |
l, ^J, KEY_RIGHT, KEY_ENTER | enter |
r | reload |
^R | reload-all |
d | mark-read; jump-to-next |
D | mark-unread; jump-to-next |
^D | mark-read-all |
(not set) | mark-unread-all |
f | mark-important |
F | mark-unimportant |
tab, e | toggle-explore-mode |
v | status-history-menu |
o | open-in-browser |
y, c | copy-to-clipboard |
/ | start-search-input |
h, ^?, KEY_LEFT, KEY_BACKSPACE | navigate-back |
q | quit |
Q | quit-hard |
Data formats of feeds which Newsraft recognizes. Not the whole functionality of these formats is implemented, but only the functionality that is most likely to carry the most essential information.
RSS 2.0, 1.1, 1.0, 0.94, 0.93,
0.92, 0.91, 0.9
Atom 1.0
RSS Content Module
Media RSS
DublinCore 1.1 Elements
JSON Feed
Newsraft's behavior depends on the environment variables set, however not all environment variables affect Newsraft directly - many environment variables affect libraries that Newsraft is built on. Thus, ncurses(3) and libcurl(3) recognize a large number of different environment variables which you can learn more about on ncurses(3) and libcurl-env(3) respectively.
However, there is one significant ncurses(3) environment variable that is worth mentioning here - ESCDELAY. It sets delay for reading Escape key. It may surprise you that its default value is 1000 ms, which is well explained in ncurses(3), but many may prefer a value much less than that or even 0.
Directory for applications to store their configuration.
Directory for applications to store their data.
Home directory of your user.
Web browser of your user.
Identifier of the Wayland graphics display.
Identifier of the X graphics display.
Setting that forcibly makes the interface monochrome when set.
mpv(1), feh(1), sqlite3(1), strftime(3), ncurses(3), libcurl(3), libcurl-env(3)
Don't be ridiculous...
Grigory Kirillov <txgk@bk.ru>
2024-03-31 |