path: root/sfeed_curses.1

.Dd January 19, 2022
.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
Interrupt: when searching it cancels the line editor, otherwise it quits.
.It 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