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.

1 files changed, 50 insertions, 34 deletions

diff --git a/sfeedrc.5 b/sfeedrc.5
index 6bdc6ca..00b912e 100644
--- 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