man page improvements

12 files changed, 69 insertions, 46 deletions

diff --git a/sfeed.1 b/sfeed.1
index ed93775..bb3f074 100644
--- a/sfeed.1
+++ b/sfeed.1
@@ -1,4 +1,4 @@
-.Dd July 6, 2021
+.Dd July 29, 2021
 .Dt SFEED 1
 .Os
 .Sh NAME
@@ -11,21 +11,18 @@
 .Nm
 reads RSS or Atom feed data (XML) from stdin.
 It writes the feed data in a TAB-separated format to stdout.
-A
-.Ar baseurl
-can be specified if the links or enclosures in the feed are relative URLs.
 If the
 .Ar baseurl
-is a valid absolute URL then the relative links or enclosures will be
-made absolute.
+argument is a valid absolute URL then the relative links or enclosures will be
+made an absolute URL.
 .Sh TAB-SEPARATED FORMAT FIELDS
-The items are output per line in a TSV-like format.
+The items are output per line in a TAB-separated format.
 .Pp
-The fields: title, id, author are not allowed to have newlines and TABs, all
-whitespace characters are replaced by a single space character.
+For the fields title, id and author each whitespace character is replaced by a
+SPACE character.
 Control characters are removed.
 .Pp
-The content field can contain newlines and is escaped.
+The content field can contain newlines and these are escaped.
 TABs, newlines and '\\' are escaped with '\\', so it becomes: '\\t', '\\n'
 and '\\\\'.
 Other whitespace characters except spaces are removed.
@@ -66,7 +63,5 @@ curl -s 'https://codemadness.org/atom.xml' | sfeed
 .Sh AUTHORS
 .An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org
 .Sh CAVEATS
-If a timezone is not in the RFC-822 or RFC-3339 format it is not supported and
-the UNIX timestamp is interpreted as UTC+0.
-.Pp
-HTML in titles is treated as plain-text.
+If a timezone for the timestamp field is not in the RFC822 or RFC3339 format it
+is not supported and the timezone is interpreted as UTC+0.
diff --git a/sfeed.5 b/sfeed.5
index b8458b2..00ed104 100644
--- a/sfeed.5
+++ b/sfeed.5
@@ -1,4 +1,4 @@
-.Dd July 6, 2021
+.Dd July 29, 2021
 .Dt SFEED 5
 .Os
 .Sh NAME
@@ -10,13 +10,13 @@
 .Xr sfeed 1
 writes the feed data in a TAB-separated format to stdout.
 .Sh TAB-SEPARATED FORMAT FIELDS
-The items are output per line in a TSV-like format.
+The items are output per line in a TAB-separated format.
 .Pp
-The fields: title, id, author are not allowed to have newlines and TABs, all
-whitespace characters are replaced by a single space character.
+For the fields title, id and author each whitespace character is replaced by a
+SPACE character.
 Control characters are removed.
 .Pp
-The content field can contain newlines and is escaped.
+The content field can contain newlines and these are escaped.
 TABs, newlines and '\\' are escaped with '\\', so it becomes: '\\t', '\\n'
 and '\\\\'.
 Other whitespace characters except spaces are removed.
@@ -49,7 +49,5 @@ Item, categories, multiple values are separated by |.
 .Sh AUTHORS
 .An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org
 .Sh CAVEATS
-If a timezone is not in the RFC-822 or RFC-3339 format it is not supported and
-the UNIX timestamp is interpreted as UTC+0.
-.Pp
-HTML in titles is treated as plain-text.
+If a timezone for the timestamp field is not in the RFC822 or RFC3339 format it
+is not supported and the timezone is interpreted as UTC+0.
diff --git a/sfeed_atom.1 b/sfeed_atom.1
index 0a332a0..4e669b0 100644
--- a/sfeed_atom.1
+++ b/sfeed_atom.1
@@ -1,4 +1,4 @@
-.Dd July 25, 2021
+.Dd July 31, 2021
 .Dt SFEED_ATOM 1
 .Os
 .Sh NAME
@@ -28,10 +28,13 @@ If
 .Nm
 is reading from one or more
 .Ar file
-it will prefix the entry title with the feed name which is the basename of the
-input file.
+arguments it will prefix the entry title with "[feed name] ".
 .Sh EXIT STATUS
 .Ex -std
+.Sh EXAMPLES
+.Bd -literal
+sfeed_atom ~/.sfeed/feeds/*
+.Ed
 .Sh SEE ALSO
 .Xr sfeed 1 ,
 .Xr sfeed_plain 1 ,
diff --git a/sfeed_frames.1 b/sfeed_frames.1
index d140cb4..e29498b 100644
--- a/sfeed_frames.1
+++ b/sfeed_frames.1
@@ -1,4 +1,4 @@
-.Dd July 25, 2021
+.Dd July 31, 2021
 .Dt SFEED_FRAMES 1
 .Os
 .Sh NAME
@@ -22,20 +22,27 @@ file is not written.
 .Pp
 Items with a timestamp from the last day compared to the system time at the
 time of formatting are counted and marked as new.
+Items are marked as new using a bold markup.
 .Pp
 There is an example style.css stylesheet file included in the distribution.
 .Sh FILES WRITTEN
 .Bl -tag -width 13n
 .It index.html
-The main HTML file referencing to the frames items.html and menu.html.
+The main HTML file referencing the files for the frames: items.html and
+menu.html.
 .It items.html
-The items frame contains all the item HTML links to the remote content.
+The HTML file of the items frame which contains all the item links to the
+feeds.
 .It menu.html
-The menu frame which contains navigation "anchor" links to the feed names in
-items.html.
+The HTML file of the menu frame which contains navigation "anchor" links (like
+"#feedname") to the feed names in items.html.
 .El
 .Sh EXIT STATUS
 .Ex -std
+.Sh EXAMPLES
+.Bd -literal
+sfeed_frames ~/.sfeed/feeds/*
+.Ed
 .Sh SEE ALSO
 .Xr sfeed 1 ,
 .Xr sfeed_html 1 ,
diff --git a/sfeed_gopher.1 b/sfeed_gopher.1
index 54ed333..a5b4e3a 100644
--- a/sfeed_gopher.1
+++ b/sfeed_gopher.1
@@ -1,4 +1,4 @@
-.Dd July 25, 2021
+.Dd July 31, 2021
 .Dt SFEED_GOPHER 1
 .Os
 .Sh NAME
@@ -22,7 +22,8 @@ arguments are specified then the basename of the
 is used as the feed name in the output.
 .Nm
 creates an index file named "index" and for each feed it creates a file with
-the same name as the feedname.
+the same name as the basename of the feed
+.Ar file .
 .Pp
 If no
 .Ar file
@@ -31,6 +32,7 @@ written to stdout and no files are written.
 .Pp
 Items with a timestamp from the last day compared to the system time at the
 time of formatting are counted and marked as new.
+Items are marked as new with the prefix "N".
 .Sh ENVIRONMENT
 .Bl -tag -width Ds
 .It Ev SFEED_GOPHER_PATH
diff --git a/sfeed_html.1 b/sfeed_html.1
index d7e2ae8..efeb289 100644
--- a/sfeed_html.1
+++ b/sfeed_html.1
@@ -1,4 +1,4 @@
-.Dd July 25, 2021
+.Dd July 31, 2021
 .Dt SFEED_HTML 1
 .Os
 .Sh NAME
@@ -26,10 +26,15 @@ is empty.
 .Pp
 Items with a timestamp from the last day compared to the system time at the
 time of formatting are counted and marked as new.
+Items are marked as new using a bold markup.
 .Pp
 There is an example style.css stylesheet file included in the distribution.
 .Sh EXIT STATUS
 .Ex -std
+.Sh EXAMPLES
+.Bd -literal
+sfeed_html ~/.sfeed/feeds/*
+.Ed
 .Sh SEE ALSO
 .Xr sfeed 1 ,
 .Xr sfeed_frames 1 ,
diff --git a/sfeed_mbox.1 b/sfeed_mbox.1
index b410351..fe1c695 100644
--- a/sfeed_mbox.1
+++ b/sfeed_mbox.1
@@ -1,4 +1,4 @@
-.Dd July 25, 2021
+.Dd July 29, 2021
 .Dt SFEED_MBOX 1
 .Os
 .Sh NAME
@@ -33,7 +33,7 @@ See the README file for some examples.
 To make further filtering simpler some custom headers are set:
 .Bl -tag -width Ds
 .It X-Feedname
-The feedname, this is the basename of the
+The feed name, this is the basename of the feed
 .Ar file .
 .El
 .Sh ENVIRONMENT VARIABLES
diff --git a/sfeed_plain.1 b/sfeed_plain.1
index 124463d..559ce77 100644
--- a/sfeed_plain.1
+++ b/sfeed_plain.1
@@ -26,6 +26,7 @@ is empty.
 .Pp
 Items with a timestamp from the last day compared to the system time at the
 time of formatting are marked as new.
+Items are marked as new with the prefix "N".
 .Pp
 .Nm
 aligns the output.
diff --git a/sfeed_twtxt.1 b/sfeed_twtxt.1
index 38ec4c9..ffc6e2d 100644
--- a/sfeed_twtxt.1
+++ b/sfeed_twtxt.1
@@ -1,4 +1,4 @@
-.Dd July 25, 2021
+.Dd July 31, 2021
 .Dt SFEED_TWTXT 1
 .Os
 .Sh NAME
@@ -23,8 +23,18 @@ If no
 .Ar file
 arguments are specified and so the data is read from stdin then the feed name
 is empty.
+.Pp
+If
+.Nm
+is reading from one or more
+.Ar file
+arguments it will prefix the entry title with "[feed name] ".
 .Sh EXIT STATUS
 .Ex -std
+.Sh EXAMPLES
+.Bd -literal
+curl -s 'https://codemadness.org/atom.xml' | sfeed | sfeed_twtxt
+.Ed
 .Sh SEE ALSO
 .Xr sfeed 1 ,
 .Xr sfeed_plain 1 ,
diff --git a/sfeed_update.1 b/sfeed_update.1
index 7e8e94e..81f2d7d 100644
--- a/sfeed_update.1
+++ b/sfeed_update.1
@@ -1,4 +1,4 @@
-.Dd July 22, 2021
+.Dd August 3, 2021
 .Dt SFEED_UPDATE 1
 .Os
 .Sh NAME
@@ -11,7 +11,7 @@
 .Nm
 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
+The items are stored as one file per feed in the directory
 .Pa $HOME/.sfeed/feeds
 by default.
 The directory can be changed in the
@@ -42,7 +42,8 @@ format containing all items per feed.
 The
 .Nm
 script merges new items with this file.
-The feedname cannot contain '/' characters, they will be replaced with '_'.
+The feed name cannot contain the '/' character because it is a path separator,
+they will be replaced with '_'.
 .El
 .Sh ENVIRONMENT VARIABLES
 .Bl -tag -width Ds
diff --git a/sfeed_web.1 b/sfeed_web.1
index c48b0f9..eb638b1 100644
--- a/sfeed_web.1
+++ b/sfeed_web.1
@@ -1,4 +1,4 @@
-.Dd July 25, 2021
+.Dd July 27, 2021
 .Dt SFEED_WEB 1
 .Os
 .Sh NAME
@@ -9,12 +9,12 @@
 .Op Ar baseurl
 .Sh DESCRIPTION
 .Nm
-reads the HTML website as XML or HTML data from stdin and writes the found
-URLs to stdout.
+reads the HTML data of the webpage from stdin and writes the found URLs to
+stdout.
 .Pp
 Such a link reference in HTML code looks like:
 .Bd -literal
-        <link rel="alternate" href="atom.xml" type="application/atom+xml" />
+	<link rel="alternate" href="atom.xml" type="application/atom+xml" />
 .Ed
 .Sh OPTIONS
 .Bl -tag -width 8n
diff --git a/sfeedrc.5 b/sfeedrc.5
index 022e696..5c24899 100644
--- a/sfeedrc.5
+++ b/sfeedrc.5
@@ -1,4 +1,4 @@
-.Dd July 6, 2021
+.Dd August 3, 2021
 .Dt SFEEDRC 5
 .Os
 .Sh NAME
@@ -35,7 +35,8 @@ function, its arguments are:
 .It Fa name
 Name of the feed, this is also used as the filename for the TAB-separated
 feed file.
-The feedname cannot contain '/' characters, they will be replaced with '_'.
+The feed name cannot contain the '/' character because it is a path separator,
+they will be replaced with '_'.
 .It Fa feedurl
 URL to fetch the RSS/Atom data from, usually a HTTP or HTTPS URL.
 .It Op Fa basesiteurl