set OS for sfeed documentation + tweaks - www.codemadness.org - www.codemadness.org saait content files (HTM) git clone git://git.codemadness.org/www.codemadness.org (DIR) Log (DIR) Files (DIR) Refs (DIR) README (DIR) LICENSE --- (DIR) commit 8b50b3d2d6302167938c042abd5cc8f383df2144 (DIR) parent 5bdabee228a3088443f6beff44a867d2dddf0a9b (HTM) Author: Hiltjo Posthuma <hiltjo@codemadness.org> Date: Fri, 10 Mar 2023 12:12:41 +0100 set OS for sfeed documentation + tweaks Diffstat: M Makefile | 10 ++++++---- M config.cfg | 2 +- A output/sfeed.1.html | 164 +++++++++++++++++++++++++++++++ A output/sfeed.1.txt | 103 +++++++++++++++++++++++++++++++ 4 files changed, 274 insertions(+), 5 deletions(-) --- (DIR) diff --git a/Makefile b/Makefile @@ -1,6 +1,6 @@ .POSIX: -generate: markdown +generate: markdown sfeeddoc mkdir -p output/phlog/ cp style.css print.css output/ # sort pages by "creation" date variable (descending), @@ -17,14 +17,16 @@ generate: markdown # raw sfeed sfeed < output/atom.xml > output/sfeed.tsv sfeed < output/atom_content.xml > output/sfeed_content.tsv - # sfeed format documentation - man -Tutf8 1 sfeed | col -b > output/sfeed.1.txt - man -Thtml 1 sfeed > output/sfeed.1.html # Atom feed page saait -t feeds/templates feeds/pages/atom.cfg # move index.gopher to index. mv output/index.gopher output/index +sfeeddoc: + # sfeed format documentation + mandoc -Ios="Some OS 1.0" -Tutf8 sfeed.1 | col -b > output/sfeed.1.txt + mandoc -Ios="Some OS 1.0" -Thtml sfeed.1 > output/sfeed.1.html + md2gopher: scripts/markdowntogopher.sh (DIR) diff --git a/config.cfg b/config.cfg @@ -1,5 +1,5 @@ # last updated the site. -siteupdated = 2023-01-30 +siteupdated = 2023-03-10 sitetitle = Codemadness siteurl = https://www.codemadness.org (DIR) diff --git a/output/sfeed.1.html b/output/sfeed.1.html @@ -0,0 +1,164 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"/> + <meta name="viewport" content="width=device-width, initial-scale=1.0"/> + <style> + table.head, table.foot { width: 100%; } + td.head-rtitle, td.foot-os { text-align: right; } + td.head-vol { text-align: center; } + .Nd, .Bf, .Op { display: inline; } + .Pa, .Ad { font-style: italic; } + .Ms { font-weight: bold; } + .Bl-diag > dt { font-weight: bold; } + code.Nm, .Fl, .Cm, .Ic, code.In, .Fd, .Fn, .Cd { font-weight: bold; + font-family: inherit; } + </style> + <title>SFEED(1)</title> +</head> +<body> +<table class="head"> + <tr> + <td class="head-ltitle">SFEED(1)</td> + <td class="head-vol">General Commands Manual</td> + <td class="head-rtitle">SFEED(1)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">sfeed</code> — <span class="Nd">RSS and + Atom parser</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<table class="Nm"> + <tr> + <td><code class="Nm">sfeed</code></td> + <td>[<var class="Ar">baseurl</var>]</td> + </tr> +</table> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp"><code class="Nm">sfeed</code> reads RSS or Atom feed data (XML) + from stdin. It writes the feed data in a TAB-separated format to stdout. If + the <var class="Ar">baseurl</var> argument is a valid absolute URL then the + relative links or enclosures will be made an absolute URL.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="TAB-SEPARATED_FORMAT_FIELDS"><a class="permalink" href="#TAB-SEPARATED_FORMAT_FIELDS">TAB-SEPARATED + FORMAT FIELDS</a></h1> +<p class="Pp">The items are output per line in a TAB-separated format.</p> +<p class="Pp">For the fields title, id and author each whitespace character is + replaced by a SPACE character. Control characters are removed.</p> +<p class="Pp">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. Control + characters are removed.</p> +<p class="Pp">The order and content of the fields are:</p> +<dl class="Bl-tag"> + <dt>1. timestamp</dt> + <dd>UNIX timestamp in UTC+0, empty if missing or on a parse failure.</dd> + <dt>2. title</dt> + <dd>Title text, HTML code in titles is ignored and is treated as + plain-text.</dd> + <dt>3. link</dt> + <dd>Link</dd> + <dt>4. content</dt> + <dd>Content, can have plain-text or HTML code depending on the content-type + field.</dd> + <dt>5. content-type</dt> + <dd>"html" or "plain" if it has content.</dd> + <dt>6. id</dt> + <dd>RSS item GUID or Atom id.</dd> + <dt>7. author</dt> + <dd>Item, first author.</dd> + <dt>8. enclosure</dt> + <dd>Item, first enclosure.</dd> + <dt>9. category</dt> + <dd>Item, categories, multiple values are separated by the '|' character.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXIT_STATUS"><a class="permalink" href="#EXIT_STATUS">EXIT + STATUS</a></h1> +<p class="Pp">The <code class="Nm">sfeed</code> utility exits 0 on + success, and >0 if an error occurs.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<div class="Bd Li"> +<pre>curl -s 'https://codemadness.org/atom.xml' | sfeed</pre> +</div> +<p class="Pp">To convert the character set from a feed that is not UTF-8 encoded + the <a class="Xr">iconv(1)</a> tool can be used:</p> +<div class="Bd Pp Li"> +<pre>curl -s 'https://codemadness.org/some_iso-8859-1_feed.xml' | \ +iconv -f iso-8859-1 -t utf-8 | \ +sfeed</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLE_SETUP"><a class="permalink" href="#EXAMPLE_SETUP">EXAMPLE + SETUP</a></h1> +<p class="Pp">1. Create a directory for the sfeedrc configuration and the + feeds:</p> +<div class="Bd Pp Li"> +<pre> mkdir -p ~/.sfeed/feeds</pre> +</div> +<p class="Pp">2. Copy the example <a class="Xr">sfeedrc(5)</a> + configuration:</p> +<div class="Bd Pp Li"> +<pre> cp sfeedrc.example ~/.sfeed/sfeedrc + $EDITOR ~/.sfeed/sfeedrc</pre> +</div> +<p class="Pp">Or import existing OPML subscriptions using + <a class="Xr">sfeed_opml_import(1)</a>:</p> +<div class="Bd Pp Li"> +<pre> sfeed_opml_import < file.opml > ~/.sfeed/sfeedrc</pre> +</div> +<p class="Pp">3. To update feeds and merge the new items with existing + items:</p> +<div class="Bd Pp Li"> +<pre> sfeed_update</pre> +</div> +<p class="Pp">4. Format feeds to a plain-text list:</p> +<div class="Bd Pp Li"> +<pre> sfeed_plain ~/.sfeed/feeds/*</pre> +</div> +<p class="Pp">Or format feeds to a curses interface:</p> +<div class="Bd Pp Li"> +<pre> sfeed_curses ~/.sfeed/feeds/*</pre> +</div> +<p class="Pp">There are also other formatting programs included. The README file + has more examples.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">sfeed_curses(1)</a>, + <a class="Xr">sfeed_opml_import(1)</a>, <a class="Xr">sfeed_plain(1)</a>, + <a class="Xr">sfeed_update(1)</a>, <a class="Xr">sfeed(5)</a>, + <a class="Xr">sfeedrc(5)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Hiltjo Posthuma</span> + <<a class="Mt" href="mailto:hiltjo@codemadness.org">hiltjo@codemadness.org</a>></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1> +<p class="Pp">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.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 7, 2023</td> + <td class="foot-os">Some OS 1.0</td> + </tr> +</table> +</body> +</html> (DIR) diff --git a/output/sfeed.1.txt b/output/sfeed.1.txt @@ -0,0 +1,103 @@ +SFEED(1) General Commands Manual SFEED(1) + +NAME + sfeed – RSS and Atom parser + +SYNOPSIS + sfeed [baseurl] + +DESCRIPTION + sfeed reads RSS or Atom feed data (XML) from stdin. It writes the feed + data in a TAB-separated format to stdout. If the baseurl argument is a + valid absolute URL then the relative links or enclosures will be made an + absolute URL. + +TAB-SEPARATED FORMAT FIELDS + The items are output per line in a TAB-separated format. + + For the fields title, id and author each whitespace character is replaced + by a SPACE character. Control characters are removed. + + 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. Control + characters are removed. + + The order and content of the fields are: + + 1. timestamp UNIX timestamp in UTC+0, empty if missing or on a parse + failure. + + 2. title Title text, HTML code in titles is ignored and is + treated as plain-text. + + 3. link Link + + 4. content Content, can have plain-text or HTML code depending on + the content-type field. + + 5. content-type "html" or "plain" if it has content. + + 6. id RSS item GUID or Atom id. + + 7. author Item, first author. + + 8. enclosure Item, first enclosure. + + 9. category Item, categories, multiple values are separated by the + '|' character. + +EXIT STATUS + The sfeed utility exits 0 on success, and >0 if an error occurs. + +EXAMPLES + curl -s 'https://codemadness.org/atom.xml' | sfeed + + To convert the character set from a feed that is not UTF-8 encoded the + iconv(1) tool can be used: + + curl -s 'https://codemadness.org/some_iso-8859-1_feed.xml' | \ + iconv -f iso-8859-1 -t utf-8 | \ + sfeed + +EXAMPLE SETUP + 1. Create a directory for the sfeedrc configuration and the feeds: + + mkdir -p ~/.sfeed/feeds + + 2. Copy the example sfeedrc(5) configuration: + + cp sfeedrc.example ~/.sfeed/sfeedrc + $EDITOR ~/.sfeed/sfeedrc + + Or import existing OPML subscriptions using sfeed_opml_import(1): + + sfeed_opml_import < file.opml > ~/.sfeed/sfeedrc + + 3. To update feeds and merge the new items with existing items: + + sfeed_update + + 4. Format feeds to a plain-text list: + + sfeed_plain ~/.sfeed/feeds/* + + Or format feeds to a curses interface: + + sfeed_curses ~/.sfeed/feeds/* + + There are also other formatting programs included. The README file has + more examples. + +SEE ALSO + sfeed_curses(1), sfeed_opml_import(1), sfeed_plain(1), sfeed_update(1), + sfeed(5), sfeedrc(5) + +AUTHORS + Hiltjo Posthuma <hiltjo@codemadness.org> + +CAVEATS + 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. + +Some OS 1.0 January 7, 2023 Some OS 1.0