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:
| M | sfeed_update.1 | | | 57 | +++++++++++++++++---------------------------------------- |
| M | sfeedrc.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
