diff options
Diffstat (limited to 'README.curses')
| -rw-r--r-- | README.curses | 176 |
1 files changed, 176 insertions, 0 deletions
diff --git a/README.curses b/README.curses new file mode 100644 index 0000000..f5e61dd --- /dev/null +++ b/README.curses @@ -0,0 +1,176 @@ +sfeed_curses +------------ + +sfeed_curses is a curses UI front-end for sfeed. + +It shows the TAB-separated feed items in a graphical command-line UI. The +interface has a look inspired by the mutt mail client. It has a sidebar panel +for the feeds, a panel with a listing of the items and a small statusbar for +the selected item/URL. Some functions like searching and scrolling are +integrated in the interface itself. + + +Build and install +----------------- + +$ make +# make install + + +Usage +----- + +Like the format programs included in sfeed you can run it like this: + + sfeed_curses ~/.sfeed/feeds/* + +... or by reading from stdin: + + sfeed_curses < ~/.sfeed/feeds/xkcd + +By default sfeed_curses marks the items of the last day as new/bold. To manage +read/unread items in a different way a plain-text file with a list of the read +URLs can be used. To enable this behaviour the path to this file can be +specified by setting the environment variable $SFEED_URL_FILE to the URL file: + + export SFEED_URL_FILE="$HOME/.sfeed/urls" + [ -f "$SFEED_URL_FILE" ] || touch "$SFEED_URL_FILE" + sfeed_curses ~/.sfeed/feeds/* + +There is a shellscript "sfeed_markread" to process the read and unread items. +See the man page for more detailed information. + + +Dependencies +------------ + +- C compiler (C99). +- libc (recommended: C99 and POSIX >= 200809). +- curses (typically ncurses), optional but recommended: but see minicurses.h. + + +Optional dependencies +--------------------- + +- POSIX make(1) for Makefile. +- mandoc for documentation: https://mdocml.bsd.lv/ + + +Run-time dependencies +--------------------- + +- A (POSIX) shell. +- A terminal (emulator) supporting UTF-8 and the used capabilities. + + +Optional run-time dependencies +------------------------------ + +- xclip for yanking the URL or enclosure. See $SFEED_YANKER to change it. +- xdg-open, used as a plumber by default. See $SFEED_PLUMBER to change it. +- awk, used by the sfeed_content and sfeed_markread script. + See the ENVIRONMENT VARIABLES section in the man page to change it. +- lynx, used by the sfeed_content script to convert HTML content. + See the ENVIRONMENT VARIABLES section in the man page to change it. + + +OS tested +--------- + +- Linux (compilers: clang, gcc, tcc, libc: glibc, musl). +- OpenBSD (clang, gcc). +- NetBSD +- FreeBSD +- DragonFlyBSD +- Illumos (OpenIndiana). +- Windows (cygwin gcc + mintty). +- HaikuOS + + +Known terminal issues +--------------------- + +Below lists some bugs or missing features in terminals that are found while +testing. Some of them might be fixed already upstream: + +- cygwin + mintty: the xterm mouse-encoding of the mouse position is broken for + scrolling. +- HaikuOS terminal: the xterm mouse-encoding of the mouse button number of the + middle-button, right-button is incorrect / reversed. +- putty: the full reset attribute (ESC c, typically `rs1`) does not reset the + window title. + + +Color themes +------------ + +To change the default theme you can set SFEED_THEME using make or in the +Makefile or include the a header file in sfeed_curses.c. See also the themes/ +directory. + + +Running custom commands inside the program +------------------------------------------ + +Running commands inside the program can be useful for example to sync items or +mark all items across all feeds as read. It can be comfortable to have a +keybind for this inside the program to perform a scripted action and then +reload the feeds by sending the signal SIGHUP. + +In the input handling code you can then add a case: + + case 'M': + forkexec((char *[]) { "markallread.sh", NULL }, 0); + break; + +or + + case 'S': + forkexec((char *[]) { "syncnews.sh", NULL }, 1); + break; + +The specified script should be in $PATH or an absolute path. + +Example of a `markallread.sh` shellscript to mark all URLs as read: + + #!/bin/sh + # mark all items/URLs as read. + + tmp=$(mktemp) + (cat ~/.sfeed/urls; cut -f 3 ~/.sfeed/feeds/*) | \ + awk '!x[$0]++' > "$tmp" && + mv "$tmp" ~/.sfeed/urls && + pkill -SIGHUP sfeed_curses # reload feeds. + +Example of a `syncnews.sh` shellscript to update the feeds and reload them: + + #!/bin/sh + sfeed_update && pkill -SIGHUP sfeed_curses + + +Open an URL directly in the same terminal +----------------------------------------- + +To open an URL directly in the same terminal using the text-mode lynx browser: + + SFEED_PLUMBER=lynx SFEED_PLUMBER_INTERACTIVE=1 sfeed_curses ~/.sfeed/feeds/* + + +Yank to tmux buffer +------------------- + +This changes the yank command to set the tmux buffer, instead of X11 xclip: + + SFEED_YANKER="tmux set-buffer \`cat\`" + + +License +------- + +ISC, see LICENSE file. + + +Author +------ + +Hiltjo Posthuma <hiltjo@codemadness.org> |