commit 702fd5193030cae25c199e7c4dba7a9be1ba89cc
parent 7199cd10a97e9d648b594cf6327f9ed7fa732527
Author: Hiltjo Posthuma <hiltjo@codemadness.org>
Date: Tue, 27 Jul 2021 11:25:02 +0200
man page improvements
Diffstat:
12 files changed, 69 insertions(+), 46 deletions(-)
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
