sfeedrc.5 (4463B) - raw


      1 .Dd August 5, 2021
      2 .Dt SFEEDRC 5
      3 .Os
      4 .Sh NAME
      5 .Nm sfeedrc
      6 .Nd sfeed_update(1) configuration file
      7 .Sh DESCRIPTION
      8 .Nm
      9 is the configuration file for
     10 .Xr sfeed_update 1 .
     11 .Sh VARIABLES
     12 .Bl -tag -width Ds
     13 .It Va sfeedpath
     14 can be set for the directory to store the TAB-separated feed files.
     15 The default is
     16 .Pa $HOME/.sfeed/feeds .
     17 .It Va maxjobs
     18 can be used to change the amount of concurrent
     19 .Fn feed
     20 jobs.
     21 The default is 8.
     22 .El
     23 .Sh FUNCTIONS
     24 .Bl -tag -width Ds
     25 .It Fn feeds
     26 This function is the required "main" entry-point function called from
     27 .Xr sfeed_update 1 .
     28 .It Fn feed "name" "feedurl" "basesiteurl" "encoding"
     29 Inside the
     30 .Fn feeds
     31 function feeds can be defined by calling the
     32 .Fn feed
     33 function, its arguments are:
     34 .Bl -tag -width Ds
     35 .It Fa name
     36 Name of the feed, this is also used as the filename for the TAB-separated
     37 feed file.
     38 The feed name cannot contain the '/' character because it is a path separator,
     39 they will be replaced with '_'.
     40 .It Fa feedurl
     41 URL to fetch the RSS/Atom data from, usually a HTTP or HTTPS URL.
     42 .It Op Fa basesiteurl
     43 Base URL of the feed links.
     44 This argument allows to fix relative item links.
     45 .Pp
     46 According to the RSS and Atom specification feeds should always have absolute
     47 URLs, however this is not always the case in practise.
     48 .It Op Fa encoding
     49 Feeds are decoded from this name to UTF-8, the name should be a usable
     50 character-set for the
     51 .Xr iconv 1
     52 tool.
     53 .El
     54 .El
     55 .Sh OVERRIDE FUNCTIONS
     56 Because
     57 .Xr sfeed_update 1
     58 is a shellscript each function can be overridden to change its behaviour,
     59 notable functions are:
     60 .Bl -tag -width Ds
     61 .It Fn fetch "name" "url" "feedfile"
     62 Fetch feed from URL and writes data to stdout, its arguments are:
     63 .Bl -tag -width Ds
     64 .It Fa name
     65 Specified name in configuration file (useful for logging).
     66 .It Fa url
     67 Url to fetch.
     68 .It Fa feedfile
     69 Used feedfile (useful for comparing modification times).
     70 .El
     71 .Pp
     72 By default the tool
     73 .Xr curl 1
     74 is used.
     75 .It Fn convertencoding "name" "from" "to"
     76 Convert from text-encoding to another and writes it to stdout, its arguments
     77 are:
     78 .Bl -tag -width Ds
     79 .It Fa name
     80 Feed name.
     81 .It Fa from
     82 From text-encoding.
     83 .It Fa to
     84 To text-encoding.
     85 .El
     86 .Pp
     87 By default the tool
     88 .Xr iconv 1
     89 is used.
     90 .It Fn parse "name" "feedurl" "basesiteurl"
     91 Parse and convert RSS/Atom XML to the
     92 .Xr sfeed 5
     93 TSV format.
     94 .Bl -tag -width Ds
     95 .It Fa name
     96 Name of the feed.
     97 .It Fa feedurl
     98 URL of the feed.
     99 .It Fa basesiteurl
    100 Base URL of the feed links.
    101 This argument allows to fix relative item links.
    102 .El
    103 .It Fn filter "name"
    104 Filter
    105 .Xr sfeed 5
    106 data from stdin, write to stdout, its arguments are:
    107 .Bl -tag -width Ds
    108 .It Fa name
    109 Feed name.
    110 .El
    111 .It Fn merge "name" "oldfile" "newfile"
    112 Merge data of oldfile with newfile and writes it to stdout, its arguments are:
    113 .Bl -tag -width Ds
    114 .It Fa name
    115 Feed name.
    116 .It Fa oldfile
    117 Old file.
    118 .It Fa newfile
    119 New file.
    120 .El
    121 .It Fn order "name"
    122 Sort
    123 .Xr sfeed 5
    124 data from stdin, write to stdout, its arguments are:
    125 .Bl -tag -width Ds
    126 .It Fa name
    127 Feed name.
    128 .El
    129 .El
    130 .Sh EXAMPLES
    131 An example configuration file is included named sfeedrc.example and also
    132 shown below:
    133 .Bd -literal
    134 #sfeedpath="$HOME/.sfeed/feeds"
    135 
    136 # list of feeds to fetch:
    137 feeds() {
    138 	# feed <name> <feedurl> [basesiteurl] [encoding]
    139 	feed "codemadness" "https://www.codemadness.nl/atom.xml"
    140 	feed "explosm" "http://feeds.feedburner.com/Explosm"
    141 	feed "golang github releases" "https://github.com/golang/go/releases.atom"
    142 	feed "linux kernel" "https://www.kernel.org/feeds/kdist.xml" "https://www.kernel.org"
    143 	feed "reddit openbsd" "https://old.reddit.com/r/openbsd/.rss"
    144 	feed "slashdot" "http://rss.slashdot.org/Slashdot/slashdot" "http://slashdot.org"
    145 	feed "tweakers" "http://feeds.feedburner.com/tweakers/mixed" "http://tweakers.net" "iso-8859-1"
    146 	# get youtube Atom feed: curl -s -L 'https://www.youtube.com/user/gocoding/videos' | sfeed_web | cut -f 1
    147 	feed "youtube golang" "https://www.youtube.com/feeds/videos.xml?channel_id=UCO3LEtymiLrgvpb59cNsb8A"
    148 	feed "xkcd" "https://xkcd.com/atom.xml" "https://xkcd.com"
    149 }
    150 .Ed
    151 .Pp
    152 To change the default
    153 .Xr curl 1
    154 options for fetching the data, the
    155 .Fn fetch
    156 function can be overridden and added at the top of the
    157 .Nm
    158 file:
    159 .Bd -literal
    160 # fetch(name, url, feedfile)
    161 fetch() {
    162 	# allow for 1 redirect, hide User-Agent, timeout is 15 seconds.
    163 	curl -L --max-redirs 1 -H "User-Agent:" -f -s -m 15 \\
    164 		"$2" 2>/dev/null
    165 }
    166 .Ed
    167 .Sh SEE ALSO
    168 .Xr curl 1 ,
    169 .Xr iconv 1 ,
    170 .Xr sfeed_update 1 ,
    171 .Xr sh 1
    172 .Sh AUTHORS
    173 .An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org