sfeed_curses.1 (9937B) - raw


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