sfeed_curses.1 (raw) (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