sfeed

Simple RSS and Atom feed parser
git clone https://git.sinitax.com/codemadness/sfeed
Log | Files | Refs | README | LICENSE | Upstream | sfeed.txt

commit ff6e334d311e35e330d43c543d0709a619c85655
parent 72e9926a6156f6c9dc465616f4cf73593ab92d03
Author: Hiltjo Posthuma <hiltjo@codemadness.org>
Date:   Tue,  4 Feb 2020 22:05:06 +0100

man page improvements

- sfeedrc.5: use the same order as executed in the sfeed_update file.
- sfeedrc.5: reference iconv and curl, which are option, but used by default.
- sfeedrc.5: use a .Sh VARIABLES section for sfeedpath and maxjobs.
- sfeed_update.1: split config format-specific documentation and reference it.
- just use the term "url" instead of "uri".
- shorten some texts, increasing readability.

Diffstat:
Msfeed_update.1 | 57+++++++++++++++++----------------------------------------
Msfeedrc.5 | 84+++++++++++++++++++++++++++++++++++++++++++++++--------------------------------
2 files changed, 67 insertions(+), 74 deletions(-)

diff --git a/sfeed_update.1 b/sfeed_update.1 @@ -1,4 +1,4 @@ -.Dd July 20, 2019 +.Dd February 4, 2020 .Dt SFEED_UPDATE 1 .Os .Sh NAME @@ -9,64 +9,40 @@ .Op Ar sfeedrc .Sh DESCRIPTION .Nm -updates feeds files and merges the new data with the previous files. -These are the files in the directory +writes TAB-separated feed files and merges new items with the items in any +existing files. +The items are stored in one file per feed in the directory .Pa $HOME/.sfeed/feeds by default. +The directory can be changed in the +.Xr sfeedrc 5 +file. .Sh OPTIONS .Bl -tag -width 17n .It Ar sfeedrc -Config file, if not specified uses the path -.Pa $HOME/.sfeed/sfeedrc -by default. -See the -.Sx FILES READ -section for more information. +Config file. +The default is +.Pa $HOME/.sfeed/sfeedrc . .El .Sh FILES READ .Bl -tag -width 17n .It Ar sfeedrc -Config file, see the sfeedrc.example file for an example. This file is evaluated as a shellscript in .Nm . -.Pp -Atleast the following functions can be overridden per feed: -.Bl -tag -width 17n -.It Fn fetch -to use -.Xr wget 1 , -OpenBSD -.Xr ftp 1 -or an other download program. -.It Fn merge -to change the merge logic. -.It Fn filter -to filter on fields. -.It Fn order -to change the sort order. -.El -.Pp -The -.Fn feeds -function is called to process the feeds. -The default -.Fn feed -function is executed concurrently as a background job in your +See also the .Xr sfeedrc 5 -config file to make updating faster. -The variable -.Va maxjobs -can be changed to limit or increase the amount of concurrent jobs (8 by -default). +man page for a detailed description of the format and an example file. .El .Sh FILES WRITTEN .Bl -tag -width 17n .It feedname -TAB-separated format containing all items per feed. +TAB-separated +.Xr sfeed 5 +format containing all items per feed. The .Nm script merges new items with this file. -The filename cannot contain '/' characters, they will be replaced with '_'. +The feedname cannot contain '/' characters, they will be replaced with '_'. .El .Sh EXAMPLES To update your feeds and format them in various formats: @@ -82,6 +58,7 @@ mkdir -p somedir && cd somedir && sfeed_frames $HOME/.sfeed/feeds/* .Ed .Sh SEE ALSO .Xr sfeed 1 , +.Xr sfeed_frames 1 , .Xr sfeed_html 1 , .Xr sfeed_plain 1 , .Xr sh 1 , diff --git a/sfeedrc.5 b/sfeedrc.5 @@ -1,4 +1,4 @@ -.Dd July 14, 2019 +.Dd February 4, 2020 .Dt SFEEDRC 5 .Os .Sh NAME @@ -8,30 +8,36 @@ .Nm is the configuration file for .Xr sfeed_update 1 . -.Pp -The variable -.Va sfeedpath -can be set for the directory to store the TAB-separated feed files, -by default this is +.Sh VARIABLES +.Bl -tag -width Ds +.It Va sfeedpath +can be set for the directory to store the TAB-separated feed files. +The default is .Pa $HOME/.sfeed/feeds . -. +.It Va maxjobs +can be used to change the amount of concurrent +.Fn feed +jobs. +The default is 8. +.El .Sh FUNCTIONS -The following functions must be defined in a -.Nm -file: .Bl -tag -width Ds .It Fn feeds -This function is like a "main" function called from +This function is the required "main" entry-point function called from .Xr sfeed_update 1 . .It Fn feed "name" "feedurl" "basesiteurl" "encoding" -Function to process the feed, its arguments are in the order: +Inside the +.Fn feeds +function feeds can be defined by calling the +.Fn feed +function, its arguments are: .Bl -tag -width Ds .It Fa name Name of the feed, this is also used as the filename for the TAB-separated feed file. -The filename cannot contain '/' characters, they will be replaced with '_'. +The feedname cannot contain '/' characters, they will be replaced with '_'. .It Fa feedurl -Uri to fetch the RSS/Atom data from, usually a HTTP or HTTPS uri. +Url to fetch the RSS/Atom data from, usually a HTTP or HTTPS url. .It Op Fa basesiteurl Baseurl of the feed links. This argument allows to fix relative item links. @@ -51,26 +57,33 @@ Because is a shellscript each function can be overridden to change its behaviour, notable functions are: .Bl -tag -width Ds -.It Fn fetch "name" "uri" "feedfile" +.It Fn fetch "name" "url" "feedfile" Fetch feed from url and writes data to stdout, its arguments are: .Bl -tag -width Ds .It Fa name Specified name in configuration file (useful for logging). -.It Fa uri -Uri to fetch. +.It Fa url +Url to fetch. .It Fa feedfile Used feedfile (useful for comparing modification times). .El -.It Fn merge "name" "oldfile" "newfile" -Merge data of oldfile with newfile and writes it to stdout, its arguments are: +.Pp +By default the tool +.Xr curl 1 +is used. +.It Fn convertencoding "from" "to" +Convert from text-encoding to another and writes it to stdout, its arguments +are: .Bl -tag -width Ds -.It Fa name -Feed name. -.It Fa oldfile -Old file. -.It Fa newfile -New file. +.It Fa from +From text-encoding. +.It Fa to +To text-encoding. .El +.Pp +By default the tool +.Xr iconv 1 +is used. .It Fn filter "name" Filter .Xr sfeed 5 @@ -79,6 +92,16 @@ data from stdin, write to stdout, its arguments are: .It Fa name Feed name. .El +.It Fn merge "name" "oldfile" "newfile" +Merge data of oldfile with newfile and writes it to stdout, its arguments are: +.Bl -tag -width Ds +.It Fa name +Feed name. +.It Fa oldfile +Old file. +.It Fa newfile +New file. +.El .It Fn order "name" Sort .Xr sfeed 5 @@ -87,15 +110,6 @@ data from stdin, write to stdout, its arguments are: .It Fa name Feed name. .El -.It Fn convertencoding "from" "to" -Convert from text-encoding to another and writes it to stdout, its arguments -are: -.Bl -tag -width Ds -.It Fa from -From text-encoding. -.It Fa to -To text-encoding. -.El .El .Sh EXAMPLES An example configuration file is included named sfeedrc.example and also @@ -119,6 +133,8 @@ feeds() { } .Ed .Sh SEE ALSO +.Xr curl 1 , +.Xr iconv 1 , .Xr sfeed_update 1 , .Xr sh 1 .Sh AUTHORS