sfeed_curses.1 - sfeed - RSS and Atom parser
(HTM) git clone git://git.codemadness.org/sfeed
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
sfeed_curses.1 (10763B)
---
1 .Dd October 27, 2024
2 .Dt SFEED_CURSES 1
3 .Os
4 .Sh NAME
5 .Nm sfeed_curses
6 .Nd curses UI for viewing feed data
7 .Sh SYNOPSIS
8 .Nm
9 .Op Ar
10 .Sh DESCRIPTION
11 .Nm
12 formats feed data (TSV) from
13 .Xr sfeed 1
14 from stdin or for each
15 .Ar file
16 into a curses UI.
17 If one or more
18 .Ar file
19 arguments are specified then the basename of the
20 .Ar file
21 is used as the feed name in the output such as the feeds sidebar.
22 The
23 .Ar file
24 arguments are processed and shown in the specified argument order in the feeds
25 sidebar.
26 If no
27 .Ar file
28 arguments are specified then the data is read from stdin and the feed name is
29 "stdin" and no sidebar is visible by default in this case.
30 .Pp
31 Items with a timestamp from the last day compared to the system time at the
32 time of loading the feed are marked as new and bold.
33 This value might be overridden through environment variables.
34 There is also an alternative mode available to mark items as read by matching
35 it against a list of URLs from a plain-text file.
36 Items with an enclosure are marked with a @ symbol.
37 .Pp
38 .Nm
39 aligns the output.
40 Make sure the environment variable
41 .Ev LC_CTYPE
42 is set to a UTF-8 locale, so it can determine the proper column-width
43 per rune, using
44 .Xr mbtowc 3
45 and
46 .Xr wcwidth 3 .
47 .Sh KEYBINDS
48 .Bl -tag -width Ds
49 .It k, ARROW UP
50 Go one row up.
51 .It j, ARROW DOWN
52 Go one row down.
53 .It K
54 Go to the previous bold row.
55 .It J
56 Go to the next bold row.
57 .It h, ARROW LEFT
58 Focus feeds pane.
59 .It l, ARROW RIGHT
60 Focus items pane.
61 .It TAB
62 Cycle focused pane (between feeds and items).
63 .It g
64 Go to the first row.
65 .It G
66 Go to the last row.
67 .It PAGE UP, CTRL-B
68 Scroll one page up.
69 .It PAGE DOWN, CTRL-F, SPACE
70 Scroll one page down.
71 .It /
72 Prompt for a new search and search forward (case-insensitive).
73 .It ?
74 Prompt for a new search and search backward (case-insensitive).
75 .It n
76 Search forward with the previously set search term.
77 .It N
78 Search backward with the previously set search term.
79 .It \&[
80 Go to the previous feed in the feeds pane and open it.
81 .It ]
82 Go to the next feed in the feeds pane and open it.
83 .It CTRL-L
84 Redraw screen.
85 .It R
86 Reload all feed files which were specified as arguments on startup.
87 If
88 .Ev SFEED_URL_FILE
89 is set, it will reload the URLs from this file also.
90 .It m
91 Toggle mouse-mode.
92 It supports xterm X10 and extended SGR encoding.
93 .It s
94 Toggle between monocle layout and the previous non-monocle layout.
95 .It <
96 Use a fixed sidebar size for the current layout and decrease the fixed width or
97 height by 1 column.
98 .It >
99 Use a fixed sidebar size for the current layout and increase the fixed width or
100 height by 1 column.
101 .It =
102 Reset the sidebar size to automatically adjust for the current layout.
103 With the vertical layout the width is the longest feed name with the item
104 counts right-aligned.
105 With the horizontal layout the height is half of the window height (minus the
106 status bar) or otherwise the total amount of visible feeds, whichever fits the
107 best.
108 .It t
109 Toggle showing only feeds with new items in the sidebar.
110 .It a, e, @
111 Plumb URL of the enclosure.
112 The URL is passed as a parameter to the program specified in
113 .Ev SFEED_PLUMBER .
114 .It o, ENTER, RETURN
115 Feeds pane: load feed and its items.
116 In the monocle layout it will also switch to the items pane after loading the
117 feed items.
118 Items pane: plumb current item URL, the URL is passed as a parameter to
119 the program specified in
120 .Ev SFEED_PLUMBER .
121 .It c, p, |
122 Pipe the whole TAB-Separated Value line to a program.
123 This program can be specified with
124 .Ev SFEED_PIPER .
125 .It y
126 Pipe the TAB-Separated Value field for yanking the URL to a program.
127 This program can be specified with
128 .Ev SFEED_YANKER .
129 .It E
130 Pipe the TAB-Separated Value field for yanking the enclosure to a program.
131 This program can be specified with
132 .Ev SFEED_YANKER .
133 .It r
134 Mark item as read.
135 This will only work when
136 .Ev SFEED_URL_FILE
137 is set.
138 .It u
139 Mark item as unread.
140 This will only work when
141 .Ev SFEED_URL_FILE
142 is set.
143 .It f
144 Mark all items of the currently loaded feed as read.
145 This will only work when
146 .Ev SFEED_URL_FILE
147 is set.
148 .It F
149 Mark all items of the currently loaded feed as unread.
150 This will only work when
151 .Ev SFEED_URL_FILE
152 is set.
153 .It 1
154 Set the current layout to a vertical mode.
155 Showing a feeds sidebar to the left and the feed items to the right.
156 .It 2
157 Set the current layout to a horizontal mode.
158 Showing a feeds sidebar on the top and the feed items on the bottom.
159 .It 3
160 Set the current layout to a monocle mode.
161 Showing either a feeds or a feed items pane.
162 .It q, EOF
163 Quit
164 .El
165 .Sh MOUSE ACTIONS
166 When mouse-mode is enabled the below actions are available.
167 .Bl -tag -width Ds
168 .It LEFT-CLICK
169 Feeds pane: select and load the feed and its items.
170 In the monocle layout it will also switch to the items pane after loading the
171 feed items.
172 Items pane: select item, when already selected then plumb it.
173 .It RIGHT-CLICK
174 Feeds pane: select feed, but do not load it.
175 Items pane: pipe the item.
176 .It SCROLL UP
177 Scroll one page up.
178 .It SCROLL DOWN
179 Scroll one page down.
180 .It FORWARD
181 Switch to the items pane.
182 .It BACKWARD
183 Switch to the feeds pane.
184 .El
185 .Sh SIGNALS
186 .Bl -tag -width Ds
187 .It SIGHUP
188 Reload all feed files which were specified as arguments on startup.
189 If
190 .Ev SFEED_URL_FILE
191 is set, it will reload the URLs from this file also.
192 Cancels the line editor and handles the signal if received during a search.
193 .It SIGINT
194 Interrupt: quit.
195 When searching, it only cancels the line editor and doesn't quit.
196 .It SIGTERM
197 Quit
198 .It SIGWINCH
199 Resize the pane dimensions relative to the terminal size.
200 When searching, it handles the signal after closing the line editor.
201 .El
202 .Pp
203 Signals are handled in the following order: SIGCHLD, SIGTERM, SIGINT, SIGHUP,
204 SIGWINCH.
205 .Sh ENVIRONMENT VARIABLES
206 .Bl -tag -width Ds
207 .It Ev SFEED_AUTOCMD
208 Read and process a sequence of keys as input commands from this environment
209 variable first, afterwards it reads from the tty as usual.
210 This can be useful to automate certain actions at the start.
211 .It Ev SFEED_NEW_AGE
212 Overwrite the maximum age in seconds to mark feeds as new.
213 By default this is 86400, which equals one day.
214 .It Ev SFEED_PIPER
215 A program where the whole TAB-Separated Value line is piped to.
216 By default this is "sfeed_content".
217 .It Ev SFEED_PIPER_INTERACTIVE
218 Handle the program interactively in the same terminal or not.
219 By default this is set to "1".
220 .It Ev SFEED_PLUMBER
221 A program that receives the link URL or enclosure URL as a parameter.
222 By default this is "xdg-open".
223 .It Ev SFEED_PLUMBER_INTERACTIVE
224 Handle the program interactively in the same terminal or not.
225 This option can be useful to open a text-mode browser in the same terminal.
226 By default this is set to "0".
227 .It Ev SFEED_YANKER
228 A program where the URL or enclosure field is piped to, to copy it to a
229 clipboard.
230 By default this is "xclip -r".
231 .It Ev SFEED_YANKER_INTERACTIVE
232 Handle the program interactively in the same terminal or not.
233 By default this is set to "0".
234 .It Ev SFEED_URL_FILE
235 If this variable is set then a different mode is used to mark items as read,
236 instead of checking the timestamp, which is the default.
237 The value specified is a plain-text file containing a list of read URLs, one
238 URL per line.
239 This URL is matched on the link field if it is set, otherwise it is matched on
240 the id field.
241 .It Ev SFEED_MARK_READ
242 A program to mark items as read if
243 .Ev SFEED_URL_FILE
244 is also set, if unset the default program used is "sfeed_markread read".
245 The marked items are piped to the program line by line.
246 If the feed item has a link then this line is the link field, otherwise it is
247 the id field.
248 The program is expected to merge items in a safe/transactional manner.
249 The program should return the exit status 0 on success or non-zero on failure.
250 .It Ev SFEED_MARK_UNREAD
251 A program to mark items as unread if
252 .Ev SFEED_URL_FILE
253 is also set, if unset the default program used is "sfeed_markread unread".
254 The unmarked items are piped to the program line by line.
255 If the feed item has a link then this line is the link field, otherwise it is
256 the id field.
257 The program is expected to merge items in a safe/transactional manner.
258 The program should return the exit status 0 on success or non-zero on failure.
259 .It Ev SFEED_LAZYLOAD
260 Lazyload items when reading the feed data from files.
261 This can reduce memory usage but increases latency when seeking items,
262 especially on slower disk drives.
263 It can also cause a race-condition issue if the feed data on disk is changed
264 while having the UI open and offsets for the lines are different.
265 A workaround for the race-condition issue is by sending the SIGHUP signal to
266 .Nm
267 after the data was updated.
268 This makes
269 .Nm
270 reload the latest feed data and update the correct line offsets.
271 By default this is set to "0".
272 .It Ev SFEED_FEED_PATH
273 This variable is set by
274 .Nm
275 when a feed is loaded.
276 If the data was read from stdin this variable is unset.
277 It can be used by the plumb or pipe program for scripting purposes.
278 .El
279 .Sh INTERACTIVE AND NON-INTERACTIVE PROGRAMS
280 .Nm
281 can pipe content, plumb and yank interactively or in a non-interactive manner.
282 In interactive mode
283 .Nm
284 waits until the process exits.
285 Stdout and stderr of the program are written as output.
286 It stores and restores the terminal attributes before and after executing the
287 program.
288 The signals SIGHUP and SIGWINCH will be handled after
289 .Nm
290 has waited on the program.
291 SIGINT is ignored while waiting on the program.
292 .Pp
293 In non-interactive mode
294 .Nm
295 doesn't wait until the process exits.
296 Stdout and stderr of the program are not written as output.
297 When plumbing an URL then stdin is closed also.
298 .Sh EXIT STATUS
299 .Ex -std
300 The exit status is 130 on SIGINT and 143 on SIGTERM.
301 .Sh EXAMPLES
302 Example:
303 .Bd -literal -offset 4n
304 sfeed_curses ~/.sfeed/feeds/*
305 .Ed
306 .Pp
307 Another example which shows some of the features
308 .Nm
309 has:
310 .Bd -literal -offset 4n
311 export SFEED_AUTOCMD="2tgo"
312 export SFEED_URL_FILE="$HOME/.sfeed/urls"
313 [ -f "$SFEED_URL_FILE" ] || touch "$SFEED_URL_FILE"
314 sfeed_curses ~/.sfeed/feeds/*
315 .Ed
316 .Pp
317 Which does the following:
318 .Bl -enum
319 .It
320 Set commands to execute automatically on startup:
321 .Pp
322 Set the current layout to a horizontal mode ('2' keybind).
323 Showing a feeds sidebar on the top and the feed items on the bottom.
324 .Pp
325 Toggle showing only feeds with new items in the sidebar ('t' keybind).
326 .Pp
327 Go to the first row in the current panel ('g' keybind).
328 .Pp
329 Load the currently selected feed ('o' keybind).
330 .It
331 Set a file to use for managing read and unread items.
332 This is a plain-text file containing a list of read URLs, one URL per line.
333 .It
334 Check if this file for managing the read and unread items exists.
335 If it doesn't exist yet then create an empty file.
336 .It
337 Start
338 .Nm
339 and read the specified feed files.
340 .El
341 .Sh SEE ALSO
342 .Xr sfeed 1 ,
343 .Xr sfeed_content 1 ,
344 .Xr sfeed_markread 1 ,
345 .Xr sfeed_plain 1 ,
346 .Xr xclip 1 ,
347 .Xr sfeed 5
348 .Sh AUTHORS
349 .An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org