sfeed

simple feed reader - forked from git.codemadness.org/sfeed
git clone git://src.gearsix.net/sfeed
Log | Files | Refs | Atom | README | LICENSE

sfeedrc.5 (4544B)

      1 .Dd January 18, 2023
      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 write the 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 data from stdin from one text-encoding to another and write it to
     77 stdout,
     78 its arguments are:
     79 .Bl -tag -width Ds
     80 .It Fa name
     81 Feed name.
     82 .It Fa from
     83 From text-encoding.
     84 .It Fa to
     85 To text-encoding.
     86 .El
     87 .Pp
     88 By default the tool
     89 .Xr iconv 1
     90 is used.
     91 .It Fn parse "name" "feedurl" "basesiteurl"
     92 Read RSS/Atom XML data from stdin, convert and write it as
     93 .Xr sfeed 5
     94 data to stdout.
     95 .Bl -tag -width Ds
     96 .It Fa name
     97 Name of the feed.
     98 .It Fa feedurl
     99 URL of the feed.
    100 .It Fa basesiteurl
    101 Base URL of the feed links.
    102 This argument allows to fix relative item links.
    103 .El
    104 .It Fn filter "name"
    105 Filter
    106 .Xr sfeed 5
    107 data from stdin and write it to stdout, its arguments are:
    108 .Bl -tag -width Ds
    109 .It Fa name
    110 Feed name.
    111 .El
    112 .It Fn merge "name" "oldfile" "newfile"
    113 Merge
    114 .Xr sfeed 5
    115 data of oldfile with newfile and write it to stdout, its arguments are:
    116 .Bl -tag -width Ds
    117 .It Fa name
    118 Feed name.
    119 .It Fa oldfile
    120 Old file.
    121 .It Fa newfile
    122 New file.
    123 .El
    124 .It Fn order "name"
    125 Sort
    126 .Xr sfeed 5
    127 data from stdin and write it to stdout, its arguments are:
    128 .Bl -tag -width Ds
    129 .It Fa name
    130 Feed name.
    131 .El
    132 .El
    133 .Sh EXAMPLES
    134 An example configuration file is included named sfeedrc.example and also
    135 shown below:
    136 .Bd -literal
    137 #sfeedpath="$HOME/.sfeed/feeds"
    138 
    139 # list of feeds to fetch:
    140 feeds() {
    141 	# feed <name> <feedurl> [basesiteurl] [encoding]
    142 	feed "codemadness" "https://www.codemadness.org/atom_content.xml"
    143 	feed "explosm" "http://feeds.feedburner.com/Explosm"
    144 	feed "golang github releases" "https://github.com/golang/go/releases.atom"
    145 	feed "linux kernel" "https://www.kernel.org/feeds/kdist.xml" "https://www.kernel.org"
    146 	feed "reddit openbsd" "https://old.reddit.com/r/openbsd/.rss"
    147 	feed "slashdot" "http://rss.slashdot.org/Slashdot/slashdot" "http://slashdot.org"
    148 	feed "tweakers" "http://feeds.feedburner.com/tweakers/mixed" "http://tweakers.net" "iso-8859-1"
    149 	# get youtube Atom feed: curl -s -L 'https://www.youtube.com/user/gocoding/videos' | sfeed_web | cut -f 1
    150 	feed "youtube golang" "https://www.youtube.com/feeds/videos.xml?channel_id=UCO3LEtymiLrgvpb59cNsb8A"
    151 	feed "xkcd" "https://xkcd.com/atom.xml" "https://xkcd.com"
    152 }
    153 .Ed
    154 .Pp
    155 To change the default
    156 .Xr curl 1
    157 options for fetching the data, the
    158 .Fn fetch
    159 function can be overridden and added at the top of the
    160 .Nm
    161 file:
    162 .Bd -literal
    163 # fetch(name, url, feedfile)
    164 fetch() {
    165 	# allow for 1 redirect, hide User-Agent, timeout is 15 seconds.
    166 	curl -L --max-redirs 1 -H "User-Agent:" -f -s -m 15 \e
    167 		"$2" 2>/dev/null
    168 }
    169 .Ed
    170 .Sh SEE ALSO
    171 .Xr curl 1 ,
    172 .Xr iconv 1 ,
    173 .Xr sfeed_update 1 ,
    174 .Xr sh 1
    175 .Sh AUTHORS
    176 .An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org