r2e.1

   1 .TH R2E 1
   2 .SH NAME
   3 r2e \- receive RSS feeds by email
   4 .SH SYNOPSIS
   5 .B r2e [options] <command> [<args>]
   6 .SH DESCRIPTION
   7 .BR r2e
   8 is a simple program which you can run in your crontab.
   9 It watches RSS feeds and sends you nicely formatted email message
  10 for each new item.
  11 .P
  12 For a quick start with \fBr2e\fR, try these steps:
  13 .P
  14 .RS 4
  15 .nf
  16 .BI "r2e new " "your@yourdomain.com"
  17 .BI "r2e add " "feedname http://feed.url/somewhere.rss"
  18 .BI "r2e run"
  19 .RE
  20 .P
  21 The last command should eventually be put into your crontab, if you
  22 want things be sent you automatically.
  23 .SH OPTIONS
  24 .TP 4
  25 \-\-help
  26 Print the rss2email help and exit.
  27 .TP
  28 \-v, \-\-version
  29 Print the rss2email version and exit.
  30 .TP
  31 \-c, \-\-config \fI<path>\fR
  32 The program configuration is read from $XDG_CONFIG_HOME/rss2mail.cfg
  33 by default (see also FILES and ENVIRONMENT VARIABLES below).  Use this
  34 option to set a different configuration file.
  35 .TP
  36 \-d, \-\-data \fI<path>\fR
  37 Dynamic program data is read from $XDG_DATA_HOME/rss2mail\&.json by
  38 default (see also FILES and ENVIRONMENT VARIABLES below).  Use this
  39 option to set a different data file.
  40 .TP
  41 \-V, \-\-verbose
  42 Increment the logging verbosity.
  43 .SH COMMANDS
  44 .TP 4
  45 .B new [\fI<email>\fR]
  46 Create a new feed database. If the \fI<email>\fR argument is given, it
  47 sets the default email address that mails are sent to.
  48 .TP
  49 .B email [\fI<email>\fR]
  50 Update the default target email address to \fI<email>\fR.
  51 .TP
  52 .B add \fI<name>\fR \fI<url>\fR [\fI<email>\fR]
  53 Subscribe to a feed. The \fI<name>\fR argument gives the feed a name
  54 for future manipulation. \fI<url>\fR is the URL of the feed.  The
  55 optional \fI<email>\fR argument is the email address to send new items
  56 to, overriding the default address for this particular feed.  Repeat
  57 for each feed you want to subscribe to.
  58 .TP
  59 .B run [\-\-no-send] [\fI<index>\fR [\fI<index>\fR ...]]
  60 Scan the feeds and send emails for new items. This can be run in a cron
  61 job.
  62 .P
  63 .RS 4
  64 The \-\-no-send option stops \fBr2e\fR from sending any email. This can be
  65 useful the first time you run it, as otherwise it would send an email
  66 for every available feed entry.
  67 .P
  68 If an \fI<index>\fR is specified, \fBr2e\fR will only download that
  69 feed. \fI<index>\fR can be either the feed name (as set by \fBadd\fR)
  70 or the feed index (as shown by \fBlist\fR).
  71 .RE
  72 .TP
  73 .B list
  74 List all the feeds in the database.
  75 .TP
  76 .B pause [\fI<index>\fR [\fI<index>\fR ...]]
  77 Pause feeds (disable fetching).  The \fI<index>\fR option selects the
  78 feed(s) to pause (see \fBrun\fR for possible values).  If no
  79 \fI<index>\fR is given, all feeds are paused.
  80 .TP
  81 .B unpause [\fI<index>\fR [\fI<index>\fR ...]]
  82 Unpause feeds (enable fetching).
  83 .TP
  84 .B delete \fI<index>\fR [\fI<index>\fR [\fI<index>\fR ...]]
  85 Remove a feed (or feeds) from the database.  The \fI<index>\fR option
  86 selects the feed(s) to delete (see \fBrun\fR for possible values).
  87 .TP
  88 .B reset [\fI<index>\fR [\fI<index>\fR ...]]
  89 Forget dynamic feed data (e.g. to re-send old entries).  The
  90 \fI<index>\fR option selects the feed(s) to reset (see \fBrun\fR for
  91 possible values).  If no \fI<index>\fR is given, all feeds are reset.
  92 .TP
  93 .B opmlimport [\fI<path>\fR]
  94 Import new feeds from OPML.  \fI<path>\fR is the file from which the
  95 OPML data will be read.  If \fI<path>\fR is not given \fBr2e\fR reads
  96 the data from stdin.
  97 .TP
  98 .B opmlexport [\fI<path>\fR]
  99 Export all feeds to OPML.  \fI<path>\fR is the file to which the OPML
 100 data will be written.  If \fI<path>\fR is not given \fBr2e\fR writes
 101 the data to stdout.
 102 .SH "CONFIGURATION"
 103 The program's behavior can be controlled via the
 104 $XDG_CONFIG_HOME/rss2email.cfg (see also FILES and ENVIRONMENT
 105 VARIABLES below). The file format is similar to a Microsoft Windows
 106 INI file.  It is parsed by Python's ConfigParser class, so see the
 107 Python documentation at
 108 http://docs\&.python\&.org/3/library/configparser\&.html for format
 109 details.
 110 .P
 111 The config file stores general configuration (applied to all feeds) in
 112 the \fB[DEFAULT]\fR section.  The \fBnew\fR command will create a
 113 configuration file for you, which you can edit as you see fit.  The
 114 \fBadd\fR command will add feed-specific sections.  To override any a
 115 setting for all feeds, change the value in the \fB[DEFAULT]\fR
 116 section.  To override a setting for a particular feed, add that
 117 setting to the feed-specific section.  Here is an example overriding
 118 \fBuse-publisher-email\fR and \fBname-format\fR for the
 119 \fBfeedname\fR feed.
 120 .P
 121 .RS 4
 122 .nf
 123 [DEFAULT]
 124 from = user@rss2email.invalid
 125 force-from = False
 126 use-publisher-email = False
 127 name-format = {feed-title}: {author}
 128   .\|.\|.
 129 verbose = warning
 130
 131 [feed.feedname]
 132 url = http://feed.url/somewhere.rss
 133 use-publisher-email = True
 134 name-format = {author} ({feed.title})
 135 .RE
 136 .P
 137 You can configure the following items:
 138 .SS Addressing
 139 .RS
 140 .IP from
 141 The email address messages are from by default
 142 .IP use-8bit
 143 Transfer-Encoding. For local mailing it is safe and
 144 convenient to use 8bit.
 145 .IP force-from
 146 True: Only use the 'from' address.
 147 False: Use the email address specified by the feed, when possible.
 148 .IP use-publisher-email
 149 True: Use the publisher's email if you can't find the author's.
 150 False: Just use the 'from' email instead.
 151 .IP name-format
 152 If empty, only use the feed email address rather than
 153 friendly name plus email address.  Available attributes may
 154 include 'feed', 'feed-title', 'author', and 'publisher', but
 155 only 'feed' is guaranteed.
 156 .IP to
 157 Set this to default To email addresses.
 158 .RE
 159 .SS Fetching
 160 .RS
 161 .IP proxy
 162 Set an HTTP proxy (e.g. 'http://your.proxy.here:8080/')
 163 .IP feed-timeout
 164 Set the timeout (in seconds) for feed server response
 165 .RE
 166 .SS Processing
 167 .RS
 168 .IP active
 169 True: Fetch, process, and email feeds.
 170 False: Don't fetch, process, or email feeds
 171 .IP digest
 172 True: Send a single, multi-entry email per feed per rss2email run.
 173 False: Send a single email per entry.
 174 .IP date-header
 175 True: Generate Date header based on item's date, when possible.
 176 False: Generate Date header based on time sent.
 177 .IP date-header-order
 178 A comma-delimited list of some combination of
 179 ('issued', 'created', 'modified', 'expired')
 180 expressing ordered list of preference in dates
 181 to use for the Date header of the email.
 182 .IP bonus-header
 183 Set this to add bonus headers to all emails
 184 Example: bonus-header = 'Approved: joe@bob.org'
 185 .IP trust-guid
 186 True: Receive one email per post.
 187 False: Receive an email every time a post changes.
 188 .IP trust-link
 189 True: Receive one email per unique link url.
 190 False: Defer to trust-guid preference.
 191 Toggling this for existing feeds may result in duplicates,
 192 because the old entries will not be recorded under their new
 193 link-based ids.
 194 .IP encodings
 195 To most correctly encode emails with international
 196 characters, we iterate through the list below and use the
 197 first character set that works.
 198 .IP post-process
 199 User processing hooks.  Note the space after the module name.
 200 Example: post-process = 'rss2email.post_process.downcase downcase_message'
 201 .IP digest-post-process
 202 User processing hooks for digest messages.  If 'digest' is
 203 enabled, the usual 'post-process' hook gets to message the
 204 per-entry messages, but this hook is called with the full
 205 digest message before it is mailed.
 206 Example: digest-post-process = 'rss2email.post_process.downcase downcase_message'
 207 .RE
 208 .SS HTML conversion
 209 .RS
 210 .IP html-mail
 211 True: Send text/html messages when possible.
 212 False: Convert HTML to plain text.
 213 .IP use-css
 214 Use CSS
 215 .IP css
 216 Optional CSS styling
 217 .RE
 218 .SS html2text options
 219 .RS
 220 .IP unicode-snob
 221 Use Unicode characters instead of their ascii psuedo-replacements
 222 .IP links-after-each-paragraph
 223 Put the links after each paragraph instead of at the end.
 224 .IP body-width
 225 Wrap long lines at position. 0 for no wrapping.
 226 .RE
 227 .SS Mailing
 228 .RS
 229 .IP email-protocol
 230 Select protocol from: sendmail, smtp, imap
 231 .IP sendmail
 232 Path to sendmail (or compatible)
 233 .RE
 234 .SS SMTP configuration
 235 .RS
 236 .IP smtp-auth
 237 Set to True to use SMTP AUTH
 238 .IP smtp-username
 239 username for SMTP AUTH
 240 .IP smtp-password
 241 password for SMTP AUTH
 242 .IP smtp-server
 243 SMTP server
 244 .IP smtp-ssl
 245 Connect to the SMTP server using SSL
 246 .IP smtp-ssl-protocol
 247 TLS/SSL version to use on STARTTLS when not using 'smtp-ssl'.
 248 .RE
 249 .SS IMAP configuration
 250 .RS
 251 .IP imap-auth
 252 set to True to use IMAP auth.
 253
 254 .IP imap-username
 255 username for IMAP authentication
 256 .IP imap-password
 257 password for IMAP authentication
 258 .IP imap-server
 259 IMAP server
 260 .IP imap-port
 261 IMAP port
 262 .IP imap-ssl
 263 connect to the IMAP server using SSL
 264 .IP imap-mailbox
 265 where we should store new messages
 266 .RE
 267 .SS Miscellaneous
 268 .RS
 269 .IP verbose
 270 Verbosity (one of 'error', 'warning', 'info', or 'debug').
 271 .RE
 272 .P
 273 .SH FILES
 274 .TP 4
 275 .B $XDG_CONFIG_HOME/rss2email.cfg
 276 If this file exists, it it read to configure the program.
 277 .TP
 278 .B $XDG_DATA_HOME/rss2email\&.json
 279 The database of feeds. Use \fBr2e\fR to add, remove, or modify feeds,
 280 do not edit it directly.
 281 .SH "ENVIRONMENT VARIABLES"
 282 The environment variables used by \fBr2e\fR are all defined in the XDG
 283 Base Directory Specification, which aims to standardize locations for
 284 user-specific configuration and data files.
 285 .TP 4
 286 .B XDG_CONFIG_HOME
 287 The preferred directory for configuration files.  Defaults to
 288 $HOME/\&.config.
 289 .TP
 290 .B XDG_DATA_HOME
 291 The preferred directory for data files.  Defaults to
 292 $HOME/\&.local/share.
 293 .TP
 294 .B XDG_CONFIG_DIRS
 295 A colon ':' separated, preference ordered list of base directories for
 296 configuration files in addition to $XDG_CONFIG_HOME.  Defaults to
 297 /etc/xdg.  If multiple configuration files are found in this path,
 298 they will all be read by the ConfigParser class (see also
 299 CONFIGURATION above).
 300 .TP
 301 .B XDG_DATA_DIRS
 302 A colon ':' separated, preference ordered list of base directories for
 303 data files.  Defaults to /usr/local/share/:/usr/share/.  Only the
 304 first matching file is used.
 305 .B
 306 .SH AUTHORS
 307 rss2email was started by Aaron Swartz, and is currently maintained by
 308 W. Trevor King.  For a more complete list of contributors, see the
 309 __contributors__ list in rss2email/__init__\&.py.
 310 .SH "REPORTING BUGS"
 311 Report bugs to the mailing list (see the README for details).