sfeed

commit 45ecf566374ff536c9cb4da90a39387cceb3ca1e
parent 3b4f656ffb12ff849939f9635f38243718640338
Author: Hiltjo Posthuma <hiltjo@codemadness.org>
Date:   Wed, 29 Jul 2015 17:42:40 +0200

update documentation regarding timezone parsing

Clarity CAVEAT concerning timezone parsing, some feeds incorrectly
use non-RFC-822 timezones in RSS feeds, this will be interpreted as
UTC+0. The formatted time will contain this timezone but without an
offset.

Diffstat:
M
README
 | 
17
++++++++++-------
M
sfeed.1
 | 
7
+++++--

2 files changed, 15 insertions(+), 9 deletions(-)
diff --git a/README b/README
@@ -72,33 +72,36 @@ sfeedrc   - Config file. This file is evaluated as a shellscript in
 Files written at runtime by sfeed_update
 ----------------------------------------
 
-feeds     - Tab-separated format containing all feeds. The sfeed_update script
+feeds     - TAB-separated format containing all feeds. The sfeed_update script
             merges new items with this file.
 feeds.new - Temporary file used by sfeed_update to merge items.
 
 
-TAB-SEPARATED format
+TAB-separated format
 --------------------
 
 The items are saved in a TSV-like format except newlines, tabs and
 backslash are escaped with \ (\n, \t and \\). Other whitespace except
 spaces are removed.
 
-The timestamp field is converted to a unix timestamp. The timestamp is also
+The timestamp field is converted to a UNIX timestamp. The timestamp is also
 stored as formatted as a separate field. The other fields are left untouched
 (including HTML).
 
 The order and format of the fields are:
 
-item unix timestamp      - string unix timestamp (GMT+0)
-item formatted timestamp - string timestamp (YYYY-mm-dd HH:MM:SS tz[+-]HHMM)
+item UNIX timestamp      - string UNIX timestamp (UTC+0)
+item formatted timestamp - string timestamp, YYYY-mm-dd HH:MM:SS (UTC[+-]HH:MM)|tz
 item title               - string
 item link                - string, absolute url, unsafe characters are encoded
 item content             - string
-item contenttype         - string ("html" or "plain")
+item contenttype         - string, "html" or "plain"
 item id                  - string
 item author              - string
-feed type                - string ("rss" or "atom")
+feed type                - string, "rss" or "atom"
+
+CAVEAT: if a timezone is not supported (non-RFC822) the UNIX timestamp is
+        interpreted as UTC+0.
 
 
 Build and install
diff --git a/sfeed.1 b/sfeed.1
@@ -23,9 +23,9 @@ removed.
 The order and format of the fields are:
 .Bl -tag -width 17n
 .It Ar item timestamp
-string, UNIX timestamp in GMT+0
+string, UNIX timestamp in UTC+0
 .It Ar item timestamp
-string, date and time in the format: YYYY-mm-dd HH:MM:SS tzname[[+-][HHMM]]
+string, date and time in the format: YYYY-mm-dd HH:MM:SS (UTC[+-][HHMM])|tz
 .It Ar item title
 string
 .It Ar item link
@@ -47,3 +47,6 @@ string, "rss" or "atom"
 .Xr sh 1
 .Sh AUTHORS
 .An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org
+.Sh CAVEATS
+if a timezone is not supported (non-RFC822) the UNIX timestamp is interpreted
+as UTC+0.