diff options
Diffstat (limited to 'sfeed_curses.1')
| -rw-r--r-- | sfeed_curses.1 | 320 |
1 files changed, 320 insertions, 0 deletions
diff --git a/sfeed_curses.1 b/sfeed_curses.1 new file mode 100644 index 0000000..264b77a --- /dev/null +++ b/sfeed_curses.1 @@ -0,0 +1,320 @@ +.Dd August 10, 2021 +.Dt SFEED_CURSES 1 +.Os +.Sh NAME +.Nm sfeed_curses +.Nd curses UI for viewing feed data +.Sh SYNOPSIS +.Nm +.Op Ar +.Sh DESCRIPTION +.Nm +formats feed data (TSV) from +.Xr sfeed 1 +from stdin or for each +.Ar file +into a curses UI. +If one or more +.Ar file +arguments are specified then the basename of the +.Ar file +is used as the feed name in the output such as the feeds sidebar. +The +.Ar file +arguments are processed and shown in the specified argument order in the feeds +sidebar. +If no +.Ar file +arguments are specified then the data is read from stdin and the feed name is +"stdin" and no sidebar is visible by default in this case. +.Pp +Items with a timestamp from the last day compared to the system time at the +time of loading the feed are marked as new and bold. +There is also an alternative mode available to mark items as read by matching +it against a list of URLs from a plain-text file. +.Pp +.Nm +aligns the output. +Make sure the environment variable +.Ev LC_CTYPE +is set to a UTF-8 locale, so it can determine the proper column-width +per rune, using +.Xr mbtowc 3 +and +.Xr wcwidth 3 . +.Sh KEYBINDS +.Bl -tag -width Ds +.It k, ARROW UP +Go one row up. +.It j, ARROW DOWN +Go one row down. +.It K +Go one row up and open the item. +.It J +Go one row down and open the item. +.It h, ARROW LEFT +Focus feeds pane. +.It l, ARROW RIGHT +Focus items pane. +.It TAB +Cycle focused pane (between feeds and items). +.It g +Go to the first row. +.It G +Go to the last row. +.It PAGE UP, CTRL-B +Scroll one page up. +.It PAGE DOWN, CTRL-F, SPACE +Scroll one page down. +.It / +Prompt for a new search and search forward (case-insensitive). +.It ? +Prompt for a new search and search backward (case-insensitive). +.It n +Search forward with the previously set search term. +.It N +Search backward with the previously set search term. +.It \&[ +Go to the previous feed in the feeds pane and open it. +.It ] +Go to the next feed in the feeds pane and open it. +.It CTRL-L +Redraw screen. +.It R +Reload all feed files which were specified as arguments on startup. +.It m +Toggle mouse-mode. +It supports xterm X10 and extended SGR encoding. +.It s +Toggle between monocle layout and the previous non-monocle layout. +.It < +Use a fixed sidebar size for the current layout and decrease the fixed width or +height by 1 column. +.It > +Use a fixed sidebar size for the current layout and increase the fixed width or +height by 1 column. +.It = +Reset the sidebar size to automaticly adjust for the current layout. +With the vertical layout the width is the longest feed name with the item +counts right-aligned. +With the horizontal layout the height is half of the window height (minus the +statusbar) or otherwise the total amount of visible feeds, whichever fits the +best. +.It t +Toggle showing only feeds with new items in the sidebar. +.It a, e, @ +Plumb URL of the enclosure. +The URL is passed as a parameter to the program specified in +.Ev SFEED_PLUMBER . +.It o, ENTER, RETURN +Feeds pane: load feed and its items. +In the monocle layout it will also switch to the items pane after loading the +feed items. +Items pane: plumb current item URL, the URL is passed as a parameter to +the program specified in +.Ev SFEED_PLUMBER . +.It c, p, | +Pipe the whole TAB-Separated Value line to a program. +This program can be specified with +.Ev SFEED_PIPER . +.It y +Pipe the TAB-Separated Value field for yanking the URL to a program. +This program can be specified with +.Ev SFEED_YANKER . +.It E +Pipe the TAB-Separated Value field for yanking the enclosure to a program. +This program can be specified with +.Ev SFEED_YANKER . +.It r +Mark item as read. +This will only work when +.Ev SFEED_URL_FILE +is set. +.It u +Mark item as unread. +This will only work when +.Ev SFEED_URL_FILE +is set. +.It f +Mark all items of the current loaded feed as read. +This will only work when +.Ev SFEED_URL_FILE +is set. +.It F +Mark all items of the current loaded feed as unread. +This will only work when +.Ev SFEED_URL_FILE +is set. +.It 1 +Set the current layout to a vertical mode. +Showing a feeds sidebar to the left and the feed items to the right. +.It 2 +Set the current layout to a horizontal mode. +Showing a feeds sidebar on the top and the feed items on the bottom. +.It 3 +Set the current layout to a monocle mode. +Showing either a feeds or a feed items pane. +.It q, EOF +Quit +.El +.Sh MOUSE ACTIONS +When mouse-mode is enabled the below actions are available. +.Bl -tag -width Ds +.It LEFT-CLICK +Feeds pane: select and load the feed and its items. +In the monocle layout it will also switch to the items pane after loading the +feed items. +Items pane: select item, when already selected then plumb it. +.It RIGHT-CLICK +Feeds pane: select feed, but do not load it. +Items pane: pipe the item. +.It SCROLL UP +Scroll one page up. +.It SCROLL DOWN +Scroll one page down. +.It FORWARD +Switch to the items pane. +.It BACKWARD +Switch to the feeds pane. +.El +.Sh SIGNALS +.Bl -tag -width Ds +.It SIGHUP +Reload all feed files which were specified as arguments on startup. +.It SIGINT, SIGTERM +Quit +.It SIGWINCH +Resize the pane dimensions relative to the terminal size. +.El +.Sh ENVIRONMENT VARIABLES +.Bl -tag -width Ds +.It Ev SFEED_AUTOCMD +Read and process a sequence of keys as input commands from this environment +variable first, afterwards read from stdin as usual. +This can be useful to automate certain actions at the start. +.It Ev SFEED_PIPER +A program where the whole TAB-Separated Value line is piped to. +By default this is "sfeed_content". +.It Ev SFEED_PIPER_INTERACTIVE +Handle the program interactively in the same terminal or not. +If set to "1" then before execution it restores the terminal attributes and +.Nm +will wait until the program is finished. +If set to "0" then it will suppress stdout and stderr output. +By default this is set to "1". +.It Ev SFEED_PLUMBER +A program that receives the link URL or enclosure URL as a parameter. +By default this is "xdg-open". +.It Ev SFEED_PLUMBER_INTERACTIVE +Handle the program interactively in the same terminal or not. +If set to "1" then before execution it restores the terminal attributes and +.Nm +will wait until the program is finished. +If set to "0" then it will suppress stdout and stderr output. +For example this option is useful to open a text-mode browser in the same +terminal. +By default this is set to "0". +.It Ev SFEED_YANKER +A program where the URL or enclosure field is piped to, to copy it to a +clipboard. +By default this is "xclip -r". +.It Ev SFEED_YANKER_INTERACTIVE +Handle the program interactively in the same terminal or not. +If set to "1" then before execution it restores the terminal attributes and +.Nm +will wait until the program is finished. +If set to "0" then it will suppress stdout and stderr output. +By default this is set to "0". +.It Ev SFEED_URL_FILE +If this variable is set then a different mode is used to mark items as read, +instead of checking the timestamp, which is the default. +The value specified is a plain-text file containing a list of read URLs, one +URL per line. +This URL is matched on the link field if it is set, otherwise it is matched on +the id field. +.It Ev SFEED_MARK_READ +A program to mark items as read if +.Ev SFEED_URL_FILE +is also set, if unset the default program used is "sfeed_markread read". +The marked items are piped to the program line by line. +If the feed item has a link then this line is the link field, otherwise it is +the id field. +The program is expected to merge items in a safe/transactional manner. +The program should return the exit status 0 on success or non-zero on failure. +.It Ev SFEED_MARK_UNREAD +A program to mark items as unread if +.Ev SFEED_URL_FILE +is also set, if unset the default program used is "sfeed_markread unread". +The unmarked items are piped to the program line by line. +If the feed item has a link then this line is the link field, otherwise it is +the id field. +The program is expected to merge items in a safe/transactional manner. +The program should return the exit status 0 on success or non-zero on failure. +.It Ev SFEED_LAZYLOAD +Lazyload items when reading the feed data from files. +This can reduce memory usage but increases latency when seeking items, +especially on slower disk drives. +It can also cause a race-condition issue if the feed data on disk is changed +while having the UI open and offsets for the lines are different. +A workaround for the race-condition issue is by sending the SIGHUP signal to +.Nm +directly after the data was updated. +This forces +.Nm +to reload the latest feed data and update the correct line offsets. +By default this is set to "0". +.It Ev SFEED_FEED_PATH +This variable is set by +.Nm +when a feed is loaded. +If the data was read from stdin this variable is unset. +It can be used by the plumb or pipe program for scripting purposes. +.El +.Sh EXIT STATUS +.Ex -std +.Sh EXAMPLES +.Bd -literal +sfeed_curses ~/.sfeed/feeds/* +.Ed +.Pp +Another example which shows some of the features +.Nm +has: +.Bd -literal +export SFEED_AUTOCMD="2tgo" +export SFEED_URL_FILE="$HOME/.sfeed/urls" +[ -f "$SFEED_URL_FILE" ] || touch "$SFEED_URL_FILE" +sfeed_curses ~/.sfeed/feeds/* +.Ed +.Pp +Which does the following: +.Bl -enum +.It +Set the current layout to a horizontal mode ('2' keybind'). +Showing a feeds sidebar on the top and the feed items on the bottom. +.It +Toggle showing only feeds with new items in the sidebar ('t' keybind). +.It +Go to the first row in the current panel ('g' keybind). +.It +Load the current selected feed ('o' keybind'). +.It +Set a file to use for managing read and unread items. +This file is a plain-text file containing a list of read URLs, one URL per +line. +.It +Check if this file for managing the read and unread items exists. +If it doesn't exist yet then create an empty file. +.It +Start +.Nm . +.El +.Sh SEE ALSO +.Xr sfeed 1 , +.Xr sfeed_content 1 , +.Xr sfeed_markread 1 , +.Xr sfeed_plain 1 , +.Xr xclip 1 , +.Xr sfeed 5 +.Sh AUTHORS +.An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org |