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