commit 1b71671a2d71c3ea8e39d4603eb8f21043d1f975
parent 379541c1eb276b5527a0c79093c5c8925628a2e1
Author: Hiltjo Posthuma <hiltjo@codemadness.org>
Date:   Thu, 27 Apr 2017 13:13:04 +0200

man pages: fix a few warnings and improve a few words

- fix new warning check (start sentence at each line).
- improve a few words.

Diffstat:
Msfeed.1 | 25++++++++++++++-----------
Msfeed.5 | 20+++++++++++---------
Msfeed_frames.1 | 17++++++++++-------
Msfeed_html.1 | 6++++--
Msfeed_mbox.1 | 12++++++++----
Msfeed_opml_import.1 | 3++-
Msfeed_plain.1 | 6++++--
Msfeed_tail.1 | 17++++++++++-------
Msfeed_update.1 | 12+++++++-----
Msfeed_web.1 | 6++++--
Msfeedrc.5 | 3++-
11 files changed, 76 insertions(+), 51 deletions(-)

diff --git a/sfeed.1 b/sfeed.1 @@ -9,21 +9,24 @@ .Op Ar baseurl .Sh DESCRIPTION .Nm -reads RSS or Atom feed data (XML) from stdin. It writes the feed data in a -TAB-separated format to stdout. A +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 in the feed are relative urls. It is -recommended to always have absolute urls in your feeds. +can be specified if the links in the feed are relative urls. +It is recommended to always have absolute urls in your feeds. .Sh TAB-SEPARATED FORMAT FIELDS The items are saved in a TSV-like 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. Control -characters are removed. +whitespace characters are replaced by a single space character. +Control characters are removed. .Pp -The content field can contain newlines and is escaped. TABs, newlines and '\\' -are escaped with '\\', so it becomes: '\\t', '\\n' and '\\\\'. Other whitespace -characters except space are removed. Control characters are removed. +The content field can contain newlines and is escaped. +TABs, newlines and '\\' are escaped with '\\', so it becomes: '\\t', '\\n' +and '\\\\'. +Other whitespace characters except spaces are removed. +Control characters are removed. .Pp The order and content of the fields are: .Bl -tag -width 17n @@ -34,8 +37,8 @@ Title text, HTML code in titles is ignored and is treated as plain-text. .It link Absolute url, unsafe characters are encoded. .It content -Content, can have plain-text or HTML code depending on the content\-type field. -.It content\-type +Content, can have plain-text or HTML code depending on the content-type field. +.It content-type "html" or "plain". .It id RSS item GUID or Atom id. diff --git a/sfeed.5 b/sfeed.5 @@ -8,18 +8,20 @@ .Nm .Sh DESCRIPTION .Xr sfeed 1 -reads RSS or Atom feed data (XML) from stdin. It writes the feed data in a -TAB-separated format to stdout. +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 The items are saved in a TSV-like 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. Control -characters are removed. +whitespace characters are replaced by a single space character. +Control characters are removed. .Pp -The content field can contain newlines and is escaped. TABs, newlines and '\\' -are escaped with '\\', so it becomes: '\\t', '\\n' and '\\\\'. Other whitespace -characters except space are removed. Control characters are removed. +The content field can contain newlines and is escaped. +TABs, newlines and '\\' are escaped with '\\', so it becomes: '\\t', '\\n' +and '\\\\'. +Other whitespace characters except spaces are removed. +Control characters are removed. .Pp The order and content of the fields are: .Bl -tag -width 17n @@ -30,8 +32,8 @@ Title text, HTML code in titles is ignored and is treated as plain-text. .It link Absolute url, unsafe characters are encoded. .It content -Content, can have plain-text or HTML code depending on the content\-type field. -.It content\-type +Content, can have plain-text or HTML code depending on the content-type field. +.It content-type "html" or "plain". .It id RSS item GUID or Atom id. diff --git a/sfeed_frames.1 b/sfeed_frames.1 @@ -11,7 +11,8 @@ .Nm formats feed data (TSV) from .Xr sfeed 1 -to HTML. It reads TSV data from stdin or +to HTML. +It reads TSV data from stdin or .Ar file and writes HTML files to the current directory. If no @@ -32,9 +33,10 @@ in items.html. .Sh FILE STRUCTURE Items for each feed category are in the format: feedname/itemname.html. The feedname and item names are normalized, whitespace characters are replaced -with a \- character, multiple whitespaces are replaced by a single \- character -and trailing whitespace will be removed. The itemname is based on the title of -the items. The feedname and title is truncated to a maximum of 128 bytes. +with a - character, multiple whitespaces are replaced by a single - character +and trailing whitespace will be removed. +The itemname is based on the title of the items. +The feedname and title is truncated to a maximum of 128 bytes. The maximum length of the path is PATH_MAX or filesystem-specific (truncated). .Sh SEE ALSO .Xr sfeed 1 , @@ -44,6 +46,7 @@ The maximum length of the path is PATH_MAX or filesystem-specific (truncated). .Sh SECURITY CONSIDERATIONS Each item content file contains the content formatted as HTML, if the feed data contains HTML like Javascripts, tracking cookies, custom styles and such -these will also be displayed. Due to the crazy nature of "the web" these things -are complex to filter. Some security and privacy can be gained by using an -adblocker, script blocker and to set your browser settings more strictly. +these will also be displayed. +Due to the crazy nature of "the web" these things are complex to filter. +Some security and privacy can be gained by using an adblocker, script blocker +and to set your browser settings more strictly. diff --git a/sfeed_html.1 b/sfeed_html.1 @@ -13,11 +13,13 @@ formats feed data (TSV) from .Xr sfeed 1 from stdin or .Ar file -to stdout in HTML. If one or more +to stdout in HTML. +If one or more .Ar file are specified, the basename of the .Ar file -is used as the feed name in the output. If no +is used as the feed name in the output. +If no .Ar file parameters are specified and so the data is read from stdin the feed name is empty. diff --git a/sfeed_mbox.1 b/sfeed_mbox.1 @@ -13,19 +13,23 @@ formats feed data (TSV) from .Xr sfeed 1 from stdin or .Ar file -to stdout in the mboxrd format. If one or more +to stdout in the mboxrd format. +If one or more .Ar file are specified, the basename of the .Ar file -is used as the feed name in the output. If no +is used as the feed name in the output. +If no .Ar file parameters are specified and so the data is read from stdin the feed name -is empty. Lines starting with "From " will be mangled in the mboxrd-style. +is empty. +Lines starting with "From " will be mangled in the mboxrd-style. The mbox data can be further processed by tools like .Xr procmail 1 or .Xr fdm 1 -for example. See the README file for some useful examples. +for example. +See the README file for some useful examples. .Sh FORMAT Depending on the original content\-type the mail will be formatted as plain-text (text/plain) or HTML (text/html). diff --git a/sfeed_opml_import.1 b/sfeed_opml_import.1 @@ -10,6 +10,7 @@ .Nm reads the OPML XML data from stdin and writes the config file text to stdout. .Sh SEE ALSO -.Xr sfeed_update 1 +.Xr sfeed_update 1 , +.Xr sfeedrc 5 .Sh AUTHORS .An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org diff --git a/sfeed_plain.1 b/sfeed_plain.1 @@ -13,11 +13,13 @@ formats feed data (TSV) from .Xr sfeed 1 from stdin or .Ar file -to stdout as a plain-text list. If one or more +to stdout as a plain-text list. +If one or more .Ar file are specified, the basename of the .Ar file -is used as the feed name in the output. If no +is used as the feed name in the output. +If no .Ar file parameters are specified and so the data is read from stdin the feed name is empty. diff --git a/sfeed_tail.1 b/sfeed_tail.1 @@ -13,26 +13,29 @@ formats unseen feed data (TSV) from .Xr sfeed 1 from stdin or .Ar file -to stdout as a plain-text list. If one or more +to stdout as a plain-text list. +If one or more .Ar file are specified, the basename of the .Ar file -is used as the feed name in the output. If no +is used as the feed name in the output. +If no .Ar file parameters are specified and so the data is read from stdin the feed name is empty. .Pp .Nm -will mark the initial items on the first run as seen. Then it will print the -initial items if data is read from stdin, if the data is read on the first -run by specifying the argument(s) +will mark the initial items on the first run as seen. +Then it will print the initial items if data is read from stdin, if the data +is read on the first run by specifying the argument(s) .Ar file it will not show the initial seen items. .Pp Unseen items are printed per line in a similar format to .Xr sfeed_plain 1 , -duplicate items are ignored. The list of unique items is determined by the -fields: feedname, item id and UNIX timestamp of the item date. +duplicate items are ignored. +The list of unique items is determined by the fields: feedname, item id and +UNIX timestamp of the item date. .Sh IMPLEMENTATION NOTES Keep in mind that because .Nm diff --git a/sfeed_update.1 b/sfeed_update.1 @@ -9,8 +9,8 @@ .Op Ar sfeedrc .Sh DESCRIPTION .Nm -updates feeds files and merges the new data with the previous files. These -are the files in the directory +updates feeds files and merges the new data with the previous files. +These are the files in the directory .Pa $HOME/.sfeed/feeds by default. .Sh OPTIONS @@ -18,7 +18,8 @@ by default. .It Ar sfeedrc Config file, if not specified uses the path .Pa $HOME/.sfeed/sfeedrc -by default. See the +by default. +See the .Sx FILES READ section for more information. .El @@ -33,8 +34,9 @@ use .Xr curl 1 , .Xr wget 1 , or an other network downloader or you can 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 concurrently as a background job to +change the merge logic. +The function feeds() is called to fetch the feeds. +By default the function feed() is executed concurrently as a background job to speedup updating. .El .Sh FILES WRITTEN diff --git a/sfeed_web.1 b/sfeed_web.1 @@ -20,10 +20,12 @@ Optional base url to use for found feed urls that are relative. url<TAB>content\-type<newline> .Bl -tag -width Ds .It url -Found absolute url. If the url is relative and the +Found absolute url. +If the url is relative and the .Ar baseurl option is -specified then the url is made absolute. If the url is relative and no +specified then the url is made absolute. +If the url is relative and no .Ar baseurl option is specified it is empty. .It content\-type diff --git a/sfeedrc.5 b/sfeedrc.5 @@ -32,7 +32,8 @@ feed file. .It feedurl Uri to fetch the RSS/Atom data from, usually a HTTP or HTTPS uri. .It Op basesiteurl -Baseurl of the feed links. This argument allows to fix relative item links. +Baseurl of the feed links. +This argument allows to fix relative item links. .Pp According to the RSS and Atom specification feeds should always have absolute urls, however this is not always the case in practise.