sfeed

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

commit 702fd5193030cae25c199e7c4dba7a9be1ba89cc
parent 7199cd10a97e9d648b594cf6327f9ed7fa732527
Author: Hiltjo Posthuma <hiltjo@codemadness.org>
Date:   Tue, 27 Jul 2021 11:25:02 +0200

man page improvements

Diffstat:
Msfeed.1 | 23+++++++++--------------
Msfeed.5 | 16+++++++---------
Msfeed_atom.1 | 9++++++---
Msfeed_frames.1 | 17++++++++++++-----
Msfeed_gopher.1 | 6++++--
Msfeed_html.1 | 7++++++-
Msfeed_mbox.1 | 4++--
Msfeed_plain.1 | 1+
Msfeed_twtxt.1 | 12+++++++++++-
Msfeed_update.1 | 7++++---
Msfeed_web.1 | 8++++----
Msfeedrc.5 | 5+++--
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