sfeed

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

commit 7e023925f48b26c1492d9fd2342c5447174e93a4
parent 2be71dd69d7a54ff076cdfaa3905b5f0e818bc03
Author: Hiltjo Posthuma <hiltjo@codemadness.org>
Date:   Fri,  2 Jan 2015 14:10:48 +0100

convert man pages to mandoc

Diffstat:
Msfeed.1 | 71++++++++++++++++++++++++++++++++++++-----------------------------------
Msfeed_frames.1 | 67++++++++++++++++++++++++++++++++++++++++---------------------------
Msfeed_html.1 | 34++++++++++++++++++++--------------
Msfeed_plain.1 | 37++++++++++++++++++++++---------------
Msfeed_update.1 | 125++++++++++++++++++++++++++++++++++++++++---------------------------------------
Msfeed_web.1 | 56++++++++++++++++++++++++++++++++++----------------------
Msfeed_xmlenc.1 | 34+++++++++++++++++++---------------
7 files changed, 235 insertions(+), 189 deletions(-)

diff --git a/sfeed.1 b/sfeed.1 @@ -1,44 +1,45 @@ -.TH SFEED 1 sfeed\-0.9 -.SH NAME -sfeed \- simple RSS and Atom parser -.SH SYNOPSIS -.B sfeed -.SH DESCRIPTION -Read XML RSS or Atom feed data from stdin. Write feed data in a +.Dd December 25, 2014 +.Dt SFEED 1 +.Os +.Sh NAME +.Nm sfeed +.Nd simple RSS and Atom parser +.Sh SYNOPSIS +.Nm sfeed +.Op Ar suffix string +.Sh DESCRIPTION +.Nm +reads RSS or Atom feed data (XML) from stdin. It writes the feed data in a tab-separated format to stdout. -.SH TAB-SEPARATED FORMAT FIELDS +.Sh TAB-SEPARATED FORMAT FIELDS +.Pp The items are saved in a TSV-like format except newlines, tabs and backslash are escaped with \\ (\\n, \\t and \\\\). Carriage returns (\\r) are removed. -.TP -.B item timestamp (unix timestamp in GMT+0) +.Pp +The order and format of the fields are: +.Pp +.Bl -tag -width 17n +.It Ar item timestamp +string, UNIX timestamp in GMT+0 +.It Ar item timestamp +string, date and time in the format: YYYY-mm-dd HH:MM:SS tzname[+-]HHMM +.It Ar item title string -.TP -.B item timestamp (formatted) -string (YYYY-mm-dd HH:MM:SS tzname[+-]HHMM) -.TP -.B item title +.It Ar item link string -.TP -.B item link +.It Ar item content string -.TP -.B item content +.It Ar item content\-type +string, "html" or "plain" +.It Ar item id string -.TP -.B item content\-type -string (html or plain) -.TP -.B item id +.It Ar item author string -.TP -.B item author -string -.TP -.B feed type -string (rss or atom) -.SH SEE ALSO -.BR sh(1) -.BR sfeed_update(1) -.SH BUGS -Please report them! +.It Ar feed type +string, "rss" or "atom" +.Sh SEE ALSO +.Xr sh 1 , +.Xr sfeed_update 1 +.Sh AUTHORS +.An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org diff --git a/sfeed_frames.1 b/sfeed_frames.1 @@ -1,29 +1,42 @@ -.TH SFEED 1 sfeed\-0.9 -.SH NAME -sfeed_frames \- format feeds file (TSV) from sfeed_update to HTML with frames -.SH SYNOPSIS -.B sfeed_frames -.RB [path] -.SH OPTIONS -.TP -.B [path] -Path to write files to, default is ".". On success path will contain the -files: index.html which is the main HTML file with the frames, -items.html which contains all the items as HTML links to the local content, -menu.html which contains navigation anchor links with the feed names -(to items.html). -.SH FILE STRUCTURE +.Dd December 25, 2014 +.Dt SFEED_FRAMES 1 +.Os +.Sh NAME +.Nm sfeed_frames +.Nd formats a feeds file to HTML with frames +.Sh SYNOPSIS +.Nm +.Op Ar directory path +.Sh DESCRIPTION +.Nm +formats a feeds file (TSV) from +.Xr sfeed_update 1 +to HTML. It reads TSV data from stdin and writes HTML to the specified +directory. For the exact TSV format see +.Xr sfeed_update 1 . +.Sh OPTIONS +.Bl -tag -width 14n +.It Ar directory path +Path to write files to, default is ".". On success the specified directory will +contain the files: +.Bl -tag -width 13n +.It Ar index.html: +this is the main HTML file referencing to the frames (items.html and +menu.html). +.It Ar items.html: +this contains all the items as HTML links to the local content. +.It Ar menu.html: +menu frame which contains navigation "anchor" links to the feed names +(in items.html). +.Sh FILE STRUCTURE +.Pp Directory for each feed category in the format: path/feedname/itemname.html. The feedname and item names are normalized, whitespace characters are replaced -with a \-, multiple whitespace is replaced by a single \- and trailing -whitespace is ignored. -.SH DESCRIPTION -Format feeds file (TSV) from sfeed_update to HTML. It reads TSV data from -stdin and writes HTML to the specified directory. For the exact TSV format -see sfeed_update(1). -.SH SEE ALSO -.BR sfeed_plain(1) -.BR sfeed_update(1) -.BR sfeed(1) -.SH BUGS -Please report them! +with a \-, multiple whitespaces are replaced by a single \- and trailing +whitespace will be removed. +.Sh SEE ALSO +.Xr sfeed_plain 1 , +.Xr sfeed_update 1 , +.Xr sfeed 1 +.Sh AUTHORS +.An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org diff --git a/sfeed_html.1 b/sfeed_html.1 @@ -1,14 +1,20 @@ -.TH SFEED 1 sfeed\-0.9 -.SH NAME -sfeed_html \- format feeds file (TSV) from sfeed_update to HTML -.SH SYNOPSIS -.B sfeed_html -.SH DESCRIPTION -Format feeds file (TSV) from sfeed_update to HTML. It reads TSV data from -stdin and writes HTML to stdout. For the exact TSV format see sfeed_update(1). -.SH SEE ALSO -.BR sfeed_plain(1) -.BR sfeed_update(1) -.BR sfeed(1) -.SH BUGS -Please report them! +.Dd December 25, 2014 +.Dt SFEED_HTML 1 +.Os +.Sh NAME +.Nm sfeed_html +.Nd formats a feeds file to HTML +.Sh SYNOPSIS +.Nm sfeed_html +.Sh DESCRIPTION +.Nm +formats a feeds file (TSV) from +.Xr sfeed_update 1 +to HTML. It reads TSV data from stdin and writes HTML to stdout. For the exact TSV format see +.Xr sfeed_update 1 . +.Sh SEE ALSO +.Xr sfeed_plain 1 , +.Xr sfeed_update 1 , +.Xr sfeed 1 +.Sh AUTHORS +.An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org diff --git a/sfeed_plain.1 b/sfeed_plain.1 @@ -1,15 +1,22 @@ -.TH SFEED 1 sfeed\-0.9 -.SH NAME -sfeed_plain \- format feeds file (TSV) from sfeed_update to plain text -.SH SYNOPSIS -.B sfeed -.SH DESCRIPTION -Format feeds file (TSV) from sfeed_update to plain text. It reads TSV data -from stdin and writes plain text to stdout. For the exact TSV format see -sfeed_update(1). -.SH SEE ALSO -.BR sfeed_html(1) -.BR sfeed_update(1) -.BR sfeed(1) -.SH BUGS -Please report them! +.Dd December 25, 2014 +.Dt SFEED_PLAIN 1 +.Os +.Sh NAME +.Nm sfeed_plain +.Nd formats a feeds file to plain text +.Sh SYNOPSIS +.Nm sfeed_plain +.Sh DESCRIPTION +.Nm +formats a feeds file (TSV) from +.Xr sfeed_update 1 +to plain text. It reads TSV data from stdin and writes formatted plain text to +stdout. For the exact TSV format see +.Xr sfeed_update 1 . +.Sh SEE ALSO +.Xr sfeed_html 1 , +.Xr sfeed_update 1 , +.Xr sfeed 1 +.Sh AUTHORS +.An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org + diff --git a/sfeed_update.1 b/sfeed_update.1 @@ -1,59 +1,63 @@ -.TH SFEED 1 sfeed\-0.9 -.SH NAME -sfeed_update \- update feeds and merge with old feeds -.SH SYNOPSIS -.B sfeed_update -.RB [configfile] -.SH OPTIONS -.TP -.B [configfile] -config file, if not specified uses the location $HOME/.sfeed/sfeedrc by default (see FILES READ section for more information). -.SH DESCRIPTION -.TP -Update feeds and merge with old feeds in the file $HOME/.sfeed/feeds by default. -.SH TAB-SEPARATED FORMAT FIELDS +.Dd December 25, 2014 +.Dt SFEED_UPDATE 1 +.Os +.Sh NAME +.Nm sfeed_update +.Nd update feeds and merge with old feeds +.Sh SYNOPSIS +.Nm +.Op Ar configfile +.Sh DESCRIPTION +.Nm +updates feeds and merges the new data with the previous feeds. This is the file +$HOME/.sfeed/feeds by default. +.Sh OPTIONS +.Bl -tag -width 17n +.It Ar configfile +config file, if not specified uses the location $HOME/.sfeed/sfeedrc by default +see the +.Sx FILES READ +section for more information. +.Sh TAB-SEPARATED FORMAT FIELDS +.Pp The items are saved in a TSV-like format except newlines, tabs and backslash are escaped with \\ (\\n, \\t and \\\\). Carriage returns (\\r) are removed. -.TP -.B timestamp (unix timestamp in GMT+0) +.Pp +The order and format of the fields are: +.Pp +.Bl -tag -width 17n +.It Ar item timestamp +string, UNIX timestamp in GMT+0 +.It Ar item timestamp +string, date and time in the format: YYYY-mm-dd HH:MM:SS tzname[+-]HHMM +.It Ar item title string -.TP -.B item timestamp (formatted) -string (YYYY-mm-dd HH:MM:SS tzname[+-]HHMM -.TP -.B item title +.It Ar item link string -.TP -.B item link +.It Ar item content string -.TP -.B item content +.It Ar item content\-type +string, "html" or "plain" +.It Ar item id string -.TP -.B item content\-type -string (html or plain) -.TP -.B item id +.It Ar item author string -.TP -.B item author +.It Ar feed type +string, "rss" or "atom" +.Sh EXTRA FIELDS +.Pp +Extra fields added by sfeed_update: +.Bl -tag -width 17n +.It Ar feed name string -.TP -.B feed type -string (rss or atom) -.TP -.B feed name -string (extra field added by sfeed_update) -.TP -.B feed url -string (extra field added by sfeed_update) -.TP -.B item baseurl site -string (extra field added by sfeed_update) -.SH FILES READ -.TP -.B sfeedrc +.It Ar feed url +string +.It Ar item baseurl site +string +.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 sfeed_update. You can for example override the fetchfeed() function to @@ -62,24 +66,23 @@ override the merge() function to change the merge logic. The function feeds() is called to fetch the feeds. By default the function feed() is executed as a parallel job to speedup updating. -.SH FILES WRITTEN -.TP -.B feeds +.Sh FILES WRITTEN +.Bl -tag -width 17n +.It Ar feeds Tab-separated format containing all feeds. The sfeed_update script merges new items with this file. -.TP -.B feeds.new +.It Ar feeds.new Temporary file used by sfeed_update to merge items. -.SH EXAMPLES -.TP +.Sh EXAMPLES +.Pp To update feeds and format the feeds file: -.nf +.Bd -literal sfeed_update "configfile" sfeed_plain < $HOME/.sfeed/feeds > $HOME/.sfeed/feeds.txt sfeed_html < $HOME/.sfeed/feeds > $HOME/.sfeed/feeds.html -.SH SEE ALSO -.BR sh(1) -.BR sfeed_plain(1) -.BR sfeed_html(1) -.SH BUGS -Please report them! +.Sh SEE ALSO +.Xr sh 1 , +.Xr sfeed_plain 1 , +.Xr sfeed_html 1 +.Sh AUTHORS +.An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org diff --git a/sfeed_web.1 b/sfeed_web.1 @@ -1,24 +1,36 @@ -.TH SFEED 1 sfeed\-0.9 -.SH NAME -sfeed_web \- find urls to feeds from a webpage -.SH SYNOPSIS -.B sfeed_web -.RB [baseurl] -.SH OPTIONS -.TP -.B [baseurl] -Optional baseurl if site uses relative urls to feed. -.SH DESCRIPTION -It reads the HTML website as XML data from stdin and writes the found urls to -stdout in the format: - -content\-type<space>url - -content\-type is usually: application/atom+xml or application/rss+xml -.SH EXAMPLES -.TP +.Dd December 25, 2014 +.Dt SFEED_WEB 1 +.Os +.Sh NAME +.Nm sfeed_web +.Nd finds urls to feeds from a HTML webpage +.Sh SYNOPSIS +.Nm +.Op Ar baseurl +.Sh DESCRIPTION +.Nm +reads the HTML website as XML or HTML data from stdin and writes the found +urls to stdout. +.Sh OPTIONS +.Bl -tag -width 8n +.It Ar baseurl +optional base url to use for found feed urls that are relative. +.Sh OUTPUT FORMAT +.Pp +content\-type<space>url<newline> +.Bl -tag -width 13n +.It Ar content\-type +Usually application/atom+xml or application/rss+xml. +.It Ar url +Found url to the feed. If the url is relative and the baseurl option is +specified then the url is changed accordingly. +.Sh EXAMPLES +.Pp Get urls from xkcd website: -.nf +.Bd -literal wget http://www.xkcd.com -q -O - | sfeed_web "http://www.xkcd.com/" -.SH BUGS -Please report them! +.Sh SEE ALSO +.Xr sh 1 , +.Xr sfeed_update 1 +.Sh AUTHORS +.An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org diff --git a/sfeed_xmlenc.1 b/sfeed_xmlenc.1 @@ -1,17 +1,21 @@ -.TH SFEED 1 sfeed\-0.9 -.SH NAME -sfeed_xmlenc \- get text\-encoding from XML -.SH SYNOPSIS -.B sfeed_xmlenc -.SH DESCRIPTION -It reads XML data from stdin and writes the found text\-encoding to stdout. -.SH EXAMPLES -.TP +.Dd December 25, 2014 +.Dt SFEED_XMLENC 1 +.Os +.Sh NAME +.Nm sfeed_xmlenc +.Nd get text\-encoding from XML +.Sh SYNOPSIS +.Nm +.Sh DESCRIPTION +.Nm +reads XML data from stdin and writes the found text\-encoding to stdout. +.Sh EXAMPLES +.Pp Get text\-encoding from xkcd Atom feed: -.nf +.Bd -literal wget http://www.xkcd.com/atom.xml -q -O - | sfeed_xmlenc -.SH SEE ALSO -.BR sh(1) -.BR sfeed_update(1) -.SH BUGS -Please report them! +.Sh SEE ALSO +.Xr sh 1 , +.Xr sfeed_update 1 +.Sh AUTHORS +.An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org