commit 4b3f099a01635e99e1112c56906ae337c1bb0ba9
parent 9fdf2b8606a56318a11074387a5aebc957c47247
Author: Hiltjo Posthuma <>
Date:   Sun, 31 Jan 2016 15:25:42 +0100

sfeedrc(5): add initial documentation for sfeedrc configuration format

MMakefile | 11+++++++++--
Asfeedrc.5 | 104+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 113 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile @@ -39,6 +39,8 @@ MAN1 = \ sfeed_update.1\ sfeed_web.1\ sfeed_xmlenc.1 +MAN5 = \ + sfeedrc.5 DOC = \ CHANGELOG\ LICENSE\ @@ -60,7 +62,7 @@ all: $(BIN) dist: $(BIN) rm -rf release/${VERSION} mkdir -p release/${VERSION} - cp -f ${MAN1} ${HDR} ${SCRIPTS} ${SRC} ${COMPATSRC} ${DOC} \ + cp -f ${MAN1} ${MAN5} ${HDR} ${SCRIPTS} ${SRC} ${DOC} \ Makefile \ sfeedrc.example style.css \ release/${VERSION}/ @@ -110,10 +112,14 @@ install: all README\ README.xml\ ${DESTDIR}${PREFIX}/share/${NAME} - # installing manual pages. + # installing manual pages for tools. mkdir -p ${DESTDIR}${MANPREFIX}/man1 cp -f ${MAN1} ${DESTDIR}${MANPREFIX}/man1 for m in $(MAN1); do chmod 644 ${DESTDIR}${MANPREFIX}/man1/$$m; done + # installing manual pages for sfeedrc(5). + mkdir -p ${DESTDIR}${MANPREFIX}/man5 + cp -f ${MAN5} ${DESTDIR}${MANPREFIX}/man5 + for m in $(MAN5); do chmod 644 ${DESTDIR}${MANPREFIX}/man5/$$m; done uninstall: # removing executable files and scripts. @@ -127,5 +133,6 @@ uninstall: -rmdir ${DESTDIR}${PREFIX}/share/${NAME} # removing manual pages. for m in $(MAN1); do rm -f ${DESTDIR}${MANPREFIX}/man1/$$m; done + for m in $(MAN5); do rm -f ${DESTDIR}${MANPREFIX}/man5/$$m; done .PHONY: all clean dist install uninstall diff --git a/sfeedrc.5 b/sfeedrc.5 @@ -0,0 +1,104 @@ +.Dd January 30, 2016 +.Dt SFEEDRC 5 +.Os +.Sh NAME +.Nm sfeedrc +.Nd sfeed_update(1) configuration file +.Sh DESCRIPTION +.Nm +is the configuration file for +.Xr sfeed_update 1 . +.Pp +The variable +.Va sfeedpath +can be set for the directory to store the feeds files, +by default this is +.Pa $HOME/.sfeed/feeds . +. +.Sh FUNCTIONS +The following functions must be defined in a +.Xr sfeedrc 5 +file: +.Bl -tag -width Ds +.It feeds +This function is like a "main" function called from +.Xr sfeed_update 1 . +.It feed +Function to process the feed, its arguments are in order: +.Bl -tag -width Ds +.It name +Name of the feed, this is also used as the filename for the feeds file. +.It feedurl +Uri to fetch the RSS/Atom data from, generally a HTTP or HTTPS uri. +.It Op basesiteurl +According to the RSS and Atom specification feeds should always have absolute +urls, however this is not always the case in practise. This option allows to +specify the base url to fix the relative urls. +.It Op encoding +Feeds are decoded from this name to utf-8, the name should be a usable +character-set for the +.Xr iconv 1 +tool. +.El +.El +.Sh OVERRIDE FUNCTIONS +Each function of +.Xr sfeed_update 1 +can be overridden to change its behaviour, notable functions are: +.Bl -tag -width Ds +.It fetchfeed +Fetch feed from url and writes data to stdout, its arguments are: +.Bl -tag -width Ds +.It uri +Uri to fetch. +.It name +Specified name in configuration file (useful for logging). +.It feedfile +Used feedfile (useful for checking modification times). +.El +.It merge +Merge data of oldfile with newfile and writes it to stdout, its arguments are: +.Bl -tag -width Ds +.It oldfile +Old file. +.It newfile +New file. +.El +.It convertencoding +Convert from text-encoding to another and writes it to stdout, its arguments +are: +.Bl -tag -width Ds +.It from +From text-encoding. +.It to +To text-encoding. +.El +.El +.Pp +See the contents of +.Xr sfeed_update 1 +for more. +.Sh EXAMPLES +An example configuration file is included named sfeedrc.example and also +shown below: +.Bd -literal +#sfeedpath="$HOME/.sfeed/feeds" + +# list of feeds to fetch: +feeds() { + # feed <name> <feedurl> [basesiteurl] [encoding] + feed "codemadness" "" + feed "explosm" "" + feed "linux kernel" "" "" + feed "slashdot" "" "" + feed "tweakers" "" "" "iso-8859-1" + # get youtube Atom feed: curl -s -L '' | sfeed_web | cut -f 1 + feed "yt golang" "" + feed "xkcd" "" "" +} +.Ed +.Sh SEE ALSO +.Xr sfeed_update 1 , +.Xr sh 1 +.Sh AUTHORS +.An Hiltjo Posthuma Aq Mt