sfeed

commit ac1ae80f3d1998d3ce3c7fa1ca933e2cda5d20fd
parent 3cb7df56e0204bb8b0799a8317ef5a5f38802c7b
Author: Hiltjo Posthuma <hiltjo@codemadness.org>
Date:   Fri, 26 Nov 2021 12:12:40 +0100

README: merge the contents of the README of sfeed_curses

Diffstat:
M
README
 | 
143
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
D
README.curses
 | 
176
-------------------------------------------------------------------------------

2 files changed, 135 insertions(+), 184 deletions(-)
diff --git 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
@@ -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 <hiltjo@codemadness.org>