r2e.1

.TH R2E 1
.SH NAME
r2e \- receive RSS feeds by email
.SH SYNOPSIS
.B r2e
.RI [ options ]
.I <command>
.RI [ <args> ]
.SH DESCRIPTION
.BR r2e
is a simple program which you can run in your
.BR crontab (5).
It watches RSS feeds and sends you nicely formatted email message
for each new item.
.P
For a quick start with
.B r2e
try these steps:
.P
.RS 4
.EX
.BI "r2e new " "your@yourdomain.com"
.BI "r2e add " "feedname http://feed.url/somewhere.rss"
.BI "r2e run"
.EE
.RE

.P
The last command should eventually be put into your crontab if you want things be sent you automatically.
.SH OPTIONS
.TP 4
\-h, \-\-help
Print the rss2email help and exit.
.TP
\-v, \-\-version
Print the rss2email version and exit.
.TP
\-\-full\-version
Print the versions of Python, the compiler used to compile Python, and
packages used by rss2email.
.TP
\-c, \-\-config \fI<path>\fR
The program configuration is read from $XDG_CONFIG_HOME/rss2mail.cfg
by default (see also FILES and ENVIRONMENT VARIABLES below).  Use this
option to set a different configuration file.
.TP
\-d, \-\-data \fI<path>\fR
Dynamic program data is read from $XDG_DATA_HOME/rss2mail\&.json by
default (see also FILES and ENVIRONMENT VARIABLES below).  Use this
option to set a different data file.
.TP
\-V, \-\-verbose
Increment the logging verbosity.
.SH COMMANDS
.TP 4
.B new \fR[\fI<email>\fR]
Create a new feed database. If the \fI<email>\fR argument is given, it
sets the default email address that mails are sent to.
.TP
.B email \fR[\fI<email>\fR]
Update the default target email address to \fI<email>\fR.
.TP
.B add \fR[\fI\-\-only-new\fR] \fI<name>\fR \fI<url>\fR [\fI<email>\fR]
Subscribe to a feed. The \fI<name>\fR argument gives the feed a name
for future manipulation. \fI<url>\fR is the URL of the feed.  The
optional \fI<email>\fR argument is the email address to send new items
to, overriding the default address for this particular feed.  Repeat
for each feed you want to subscribe to.
.P
.RS 4
The \-\-only-new option fetches the feed at addition time without
sending the entries, making subsequent \fBrun\fR execution consider
them as already having been sent. It should be used when one is only
interested in entries that are not yet in the feed at the time of
running \fBadd\fR.
.RE
.TP
.B run \fR[\fI\-\-no-send\fR] \fR[\fI\-\-clean\fR] \fR[\fI<index>\fR [\fI<index>\fR ...]]
Scan the feeds and send emails for new items. This can be run in a cron
job.
.P
.RS 4
The \-\-no-send option stops \fBr2e\fR from sending any email. This can be
useful the first time you run it, as otherwise it would send an email
for every available feed entry.
.P
The \-\-clean option reduces the database size by removing old entries. It
forces a download of selected feeds or all feeds, and should only be used
weekly or monthly.
.P
If an \fI<index>\fR is specified, \fBr2e\fR will only download that
feed. \fI<index>\fR can be either the feed name (as set by \fBadd\fR)
or the feed index (as shown by \fBlist\fR).
.RE
.TP
.B list
List all the feeds in the database.
.TP
.B pause \fR[\fI<index>\fR [\fI<index>\fR ...]]
Pause feeds (disable fetching).  The \fI<index>\fR option selects the
feed(s) to pause (see \fBrun\fR for possible values).  If no
\fI<index>\fR is given, all feeds are paused.
.TP
.B unpause \fR[\fI<index>\fR [\fI<index>\fR ...]]
Unpause feeds (enable fetching).
.TP
.B delete \fI<index>\fR [\fI<index>\fR [\fI<index>\fR ...]]
Remove a feed (or feeds) from the database.  The \fI<index>\fR option
selects the feed(s) to delete (see \fBrun\fR for possible values).
.TP
.B reset \fR[\fI<index>\fR [\fI<index>\fR ...]]
Forget dynamic feed data (e.g. to re-send old entries).  The
\fI<index>\fR option selects the feed(s) to reset (see \fBrun\fR for
possible values).  If no \fI<index>\fR is given, all feeds are reset.
.TP
.B opmlimport \fR[\fI<path>\fR]
Import new feeds from OPML.  \fI<path>\fR is the file from which the
OPML data will be read.  If \fI<path>\fR is not given \fBr2e\fR reads
the data from stdin.
.TP
.B opmlexport \fR[\fI<path>\fR]
Export all feeds to OPML.  \fI<path>\fR is the file to which the OPML
data will be written.  If \fI<path>\fR is not given \fBr2e\fR writes
the data to stdout.
.SH "CONFIGURATION"
The program's behavior can be controlled via the
\fI$XDG_CONFIG_HOME/rss2email.cfg\fR
(see also \fBFILES\fR and \fBENVIRONMENT VARIABLES\fR below).
The file format is similar to a Microsoft Windows
INI file.  It is parsed by Python's ConfigParser class, so see the
Python documentation at
http://docs\&.python\&.org/3/library/configparser\&.html for format
details.
.P
The config file stores general configuration (applied to all feeds) in
the \fB[DEFAULT]\fR section.  The \fBnew\fR command will create a
configuration file for you, which you can edit as you see fit.  The
\fBadd\fR command will add feed-specific sections.  To override any a
setting for all feeds, change the value in the \fB[DEFAULT]\fR
section.  To override a setting for a particular feed, add that
setting to the feed-specific section.  Here is an example overriding
\fBuse-publisher-email\fR and \fBname-format\fR for the
\fBfeedname\fR feed.
.P
.RS 4
.EX
[DEFAULT]
from = user@rss2email.invalid
force-from = False
use-publisher-email = False
name-format = {feed-title}: {author}
  .\|.\|.
verbose = warning

[feed.feedname]
url = http://feed.url/somewhere.rss
use-publisher-email = True
name-format = {author} ({feed.title})
.EE
.RE
.P
You can configure the following items:
.SS Addressing
.IP from
The email address messages are from by default
.IP use-8bit
Transfer-Encoding. For local mailing it is safe and
convenient to use 8bit.
.IP force-from
True: Only use the 'from' address.
False: Use the email address specified by the feed, when possible.
.IP use-publisher-email
True: Use the publisher's email if you can't find the author's.
False: Just use the 'from' email instead.
.IP name-format
If empty, only use the feed email address rather than
friendly name plus email address.  Available attributes may
include 'feed', 'feed-name', 'feed-url', 'feed-title', 'author', and 'publisher',
but only 'feed', 'feed-name', and 'feed-url' are guaranteed.
.IP to
Set this to default To email addresses.
.RE
.SS Fetching
.IP proxy
Set an HTTP proxy (e.g. 'http://your.proxy.here:8080/')
.IP feed-timeout
Set the timeout (in seconds) for feed server response
.IP same-server-fetch-interval
Set the sleep interval (in seconds) between consecutive fetches from the same server
.RE
.SS Processing
.IP active
True: Fetch, process, and email feeds.
False: Don't fetch, process, or email feeds
.IP digest
True: Send a single, multi-entry email per feed per rss2email run.
False: Send a single email per entry.
.IP digest-type
Message content-type for digests.  Valid values are 'multipart/digest'
and 'multipart/mixed'.  The former is the default, but many mail user agents
do not support it.
.IP date-header
True: Generate Date header based on item's date, when possible.
False: Generate Date header based on time sent.
.IP date-header-order
A comma-delimited list of some combination of
('issued', 'created', 'modified', 'expired')
expressing ordered list of preference in dates
to use for the Date header of the email.
.IP bonus-header
Set this to add bonus headers to all emails
Example: bonus-header = 'Approved: joe@bob.org'
.IP trust-guid
True: Receive one email per post.
False: Receive an email every time a post changes.
.IP trust-link
True: Receive one email per unique link url.
False: Defer to trust-guid preference.
Toggling this for existing feeds may result in duplicates,
because the old entries will not be recorded under their new
link-based ids.
.IP encodings
To most correctly encode emails with international
characters, we iterate through the list below and use the
first character set that works.
.IP post-process
User processing hooks.  Note the space after the module name.
Example: post-process = 'rss2email.post_process.downcase downcase_message'
.IP digest-post-process
User processing hooks for digest messages.  If 'digest' is
enabled, the usual 'post-process' hook gets to message the
per-entry messages, but this hook is called with the full
digest message before it is mailed.
Example: digest-post-process = 'rss2email.post_process.downcase downcase_message'
.IP subject-format
The format for the Subject line.  Available attributes
are 'feed', 'feed-name', 'feed-url', 'feed-title'.
.RE
.SS HTML conversion
.IP html-mail
True: Send text/html messages when possible.
False: Convert HTML to plain text.
.IP use-css
Use CSS
.IP css
Optional CSS styling
.RE
.SS html2text options
.IP unicode-snob
Use Unicode characters instead of their ascii psuedo-replacements
.IP links-after-each-paragraph
Put the links after each paragraph instead of at the end.
.IP inline-links
Use inline, rather than reference, formatting for images and links.
.IP wrap-links
Wrap links according to body width.
.IP body-width
Wrap long lines at position. Any negative value for no wrapping, 0 for 78 width
(compatibility), or any positive width.
.RE
.SS Mailing
.IP email-protocol
Select protocol from: sendmail, smtp, imap, maildir
.IP sendmail
Path to sendmail (or compatible)
.RE
.SS SMTP configuration
.IP smtp-auth
Set to True to use SMTP AUTH
.IP smtp-username
username for SMTP AUTH
.IP smtp-password
password for SMTP AUTH
.IP smtp-server
SMTP server
.IP smtp-ssl
Connect to the SMTP server using SSL
.RE
.SS IMAP configuration
.IP imap-auth
set to True to use IMAP auth.
.IP imap-username
username for IMAP authentication
.IP imap-password
password for IMAP authentication
.IP imap-server
IMAP server
.IP imap-port
IMAP port
.IP imap-ssl
connect to the IMAP server using SSL
.IP imap-mailbox
where we should store new messages
.RE
.SS Maildir configuration
.IP maildir-path
Path of maildir to write messages into
.IP maildir-mailbox
Mailbox within maildir-path to write messages into
.RE
.SS Miscellaneous
.IP user-agent
String to use as HTTP User-Agent in web requests and as the User-Agent header in
outgoing emails. If present, __VERSION__ and __URL__ are replaced with rss2email
version number and webpage.
.IP verbose
Verbosity (one of 'error', 'warning', 'info', or 'debug').
.RE
.P
.SH FILES
.TP 4
.B $XDG_CONFIG_HOME/rss2email.cfg
If this file exists, it is read to configure the program.
.TP
.B $XDG_DATA_HOME/rss2email\&.json
The database of feeds. Use \fBr2e\fR to add, remove, or modify feeds,
do not edit it directly.
.SH "ENVIRONMENT VARIABLES"
The environment variables used by \fBr2e\fR are all defined in the XDG
Base Directory Specification, which aims to standardize locations for
user-specific configuration and data files.
.TP 4
.B XDG_CONFIG_HOME
The preferred directory for configuration files.  Defaults to
$HOME/\&.config.
.TP
.B XDG_DATA_HOME
The preferred directory for data files.  Defaults to
$HOME/\&.local/share.
.TP
.B XDG_RUNTIME_DIR
The preferred directory for lockfiles.  Defaults to
/tmp/rss2email-UID
.TP
.B XDG_CONFIG_DIRS
A colon ':' separated, preference ordered list of base directories for
configuration files in addition to $XDG_CONFIG_HOME.  Defaults to
/etc/xdg.  If multiple configuration files are found in this path,
they will all be read by the ConfigParser class (see also
CONFIGURATION above).
.TP
.B XDG_DATA_DIRS
A colon ':' separated, preference ordered list of base directories for
data files.  Defaults to /usr/local/share/:/usr/share/.  Only the
first matching file is used.
.B
.SH AUTHORS
rss2email was started by Aaron Swartz, and is currently maintained by
a group of people.  For a more complete list of contributors, see the
AUTHORS file in the rss2email distribution.
.SH "REPORTING BUGS"
Report bugs by creating an issue at
.UR https://github.com/rss2email/rss2email
.UE .