From ac1ae80f3d1998d3ce3c7fa1ca933e2cda5d20fd Mon Sep 17 00:00:00 2001 From: Hiltjo Posthuma Date: Fri, 26 Nov 2021 12:12:40 +0100 Subject: README: merge the contents of the README of sfeed_curses --- README | 143 ++++++++++++++++++++++++++++++++++++++++++++--- README.curses | 176 ---------------------------------------------------------- 2 files changed, 135 insertions(+), 184 deletions(-) delete mode 100644 README.curses diff --git a/README b/README index ab565bf..bacbcbc 100644 --- a/README +++ b/README @@ -16,6 +16,20 @@ $ make # make install +To build sfeed without sfeed_curses: + +$ make SFEED_CURSES="" +# make SFEED_CURSES="" install + + +To change the default theme you can set SFEED_THEME using make or in the +Makefile or include the header file in sfeed_curses.c. See also the themes/ +directory. + +$ make SFEED_THEME="templeos" +# make SFEED_THEME="templeos" install + + Usage ----- @@ -79,9 +93,6 @@ Gopher, SSH, etc. See the section "Usage and examples" below and the man-pages for more information how to use sfeed(1) and the additional tools. -A separate curses UI front-end called sfeed_curses is available at: -https://codemadness.org/sfeed_curses.html - Dependencies ------------ @@ -93,11 +104,11 @@ Dependencies Optional dependencies --------------------- -- POSIX make(1) for Makefile. +- POSIX make(1) for the Makefile. - POSIX sh(1), used by sfeed_update(1) and sfeed_opml_export(1). - POSIX utilities such as awk(1) and sort(1), - used by sfeed_update(1). + used by sfeed_content(1), sfeed_markread(1) and sfeed_update(1). - curl(1) binary: https://curl.haxx.se/ , used by sfeed_update(1), but can be replaced with any tool like wget(1), OpenBSD ftp(1) or hurl(1): https://git.codemadness.org/hurl/ @@ -106,6 +117,21 @@ Optional dependencies encoded then you don't need this. For a minimal iconv implementation: https://git.etalabs.net/cgit/noxcuse/tree/src/iconv.c - mandoc for documentation: https://mdocml.bsd.lv/ +- curses (typically ncurses), otherwise see minicurses.h, + used by sfeed_curses(1). +- a terminal (emulator) supporting UTF-8 and the used capabilities, + used by sfeed_curses(1). + + +Optional run-time dependencies for sfeed_curses +----------------------------------------------- + +- 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 @@ -115,14 +141,15 @@ OS tested compilers: clang, gcc, chibicc, cproc, lacc, pcc, tcc, libc: glibc, musl. - OpenBSD (clang, gcc). -- NetBSD +- NetBSD (with NetBSD curses). - FreeBSD - DragonFlyBSD -- Windows (cygwin gcc, mingw). +- Illumos (OpenIndiana). +- Windows (cygwin gcc + mintty, mingw). - HaikuOS - SerenityOS - FreeDOS (djgpp). -- FUZIX (sdcc -mz80). +- FUZIX (sdcc -mz80, with the sfeed parser program). Architectures tested @@ -137,11 +164,14 @@ Files sfeed - Read XML RSS or Atom feed data from stdin. Write feed data in TAB-separated format to stdout. sfeed_atom - Format feed data (TSV) to an Atom feed. +sfeed_content - View item content, for use with sfeed_curses. +sfeed_curses - Format feed data (TSV) to a curses interface. sfeed_frames - Format feed data (TSV) to HTML file(s) with frames. sfeed_gopher - Format feed data (TSV) to Gopher files. sfeed_html - Format feed data (TSV) to HTML. sfeed_opml_export - Generate an OPML XML file from a sfeedrc config file. sfeed_opml_import - Generate a sfeedrc config file from an OPML XML file. +sfeed_markread - Mark items as read/unread, for use with sfeed_curses. sfeed_mbox - Format feed data (TSV) to mbox. sfeed_plain - Format feed data (TSV) to a plain-text list. sfeed_twtxt - Format feed data (TSV) to a twtxt feed. @@ -228,6 +258,33 @@ View formatted output in your editor: - - - +View formatted output in a curses interface. 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. + +Just like the other 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/* + +It then uses the shellscript "sfeed_markread" to process the read and unread +items. + +- - - + Example script to view feed items in a vertical list/menu in dmenu(1). It opens the selected URL in the browser set in $BROWSER: @@ -766,6 +823,76 @@ TSV format. } }' +- - - + +Running custom commands inside the program +------------------------------------------ + +Running commands inside the sfeed_curses 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\`" + + +Known terminal issues +--------------------- + +Below lists some bugs or missing features in terminals that are found while +testing sfeed_curses. 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. + License ------- diff --git a/README.curses b/README.curses deleted file mode 100644 index f5e61dd..0000000 --- a/README.curses +++ /dev/null @@ -1,176 +0,0 @@ -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 -- cgit v1.2.3