sfeed

simple feed reader - forked from git.codemadness.org/sfeed
git clone git://src.gearsix.net/sfeedsfeed.zip
Log | Files | Refs | Atom | README | LICENSE

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