README

   1 .. -*- coding: utf-8 -*-
   2
   3 ==============================
   4 Getting Started With rss2email
   5 ==============================
   6
   7 We highly recommend that you subscribe to the rss2email project feed
   8 so you can keep up to date with the latest version, bugfixes and
   9 features:
  10
  11   http://rss.gmane.org/gmane.mail.rss2email
  12
  13 .. contents::
  14
  15 Installing rss2email
  16 ====================
  17
  18 Packages
  19 --------
  20
  21 A quick way to get rss2email going is using pre-made packages. Here
  22 are releases for Debian__ Linux, Ubuntu__ Linux, Gentoo__ Linux,
  23 openSUSE__, and NetBSD__.
  24
  25 __ `Debian package`_
  26 __ `Ubuntu package`_
  27 __ `Gentoo package`_
  28 __ `openSUSE package`_
  29 __ `NetBSD package`_
  30
  31 Installing by hand
  32 ------------------
  33
  34 Requirements
  35 ~~~~~~~~~~~~
  36
  37 Before you install rss2email, you'll need to make sure that a few
  38 things are in place.
  39
  40 1. Ensure that a version of Python_ ≥3.2 is installed.
  41 2. Install the required Python packages.
  42
  43   1. feedparser_
  44   2. html2text_
  45
  46 3. Figure out how you are going to send outgoing email.  You have two
  47    options here: either use an STMP server or a local sendmail
  48    program.  So,
  49
  50   * determine your outgoing email server's SMTP address, or
  51   * install sendmail (or a compatible replacement like postfix).
  52
  53 Download
  54 ~~~~~~~~
  55
  56 Download the latest rss2email source and unpack it.  You can choose
  57 from several equivalent formats.
  58
  59 1. A ``.zip`` file (suggested for Microsoft Windows users)::
  60
  61     $ wget https://github.com/wking/rss2email/archive/v2.71.zip
  62     $ unzip rss2email-*.zip
  63
  64 2. A ``.tar.gz`` file (suggested for everyone else)::
  65
  66     $ wget https://github.com/wking/rss2email/archive/v2.71.tar.gz
  67     $ tar xvf rss2email*.tar.gz
  68
  69 3. A Git_ checkout (suggested for developers)::
  70
  71     $ git clone git://github.com/wking/rss2email.git
  72
  73 Install
  74 ~~~~~~~
  75
  76 From the unpacked directory, run::
  77
  78   $ python setup.py install
  79
  80 You can pass all the usual options to the ``install`` command,
  81 including ``--user``.  If you don't want to install rss2email, you can
  82 also run ``r2e`` directly from the source directory.
  83
  84 Upgrading to a new version
  85 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  86
  87 Just repeat the installation procedure for the new source package.  If
  88 your config file and data file were in the old source directory, move
  89 them over to the new source directory.  If the config and data files
  90 were in another directory (e.g. ``~/.config`` and ``~/.local/share``),
  91 there is no need to move them.
  92
  93 Using rss2email
  94 ===============
  95
  96 Create a new feed database to send updates to your email address::
  97
  98   $ r2e new you@yourdomain.com
  99
 100 This command will create a configuration file
 101 (``$XDG_CONFIG_HOME/rss2email.cfs`` by default) and a feed database
 102 (``$XDG_DATA_HOME/rss2email.json`` by default).  If you'd rather those
 103 files were stored in other locations, use the ``--config`` and
 104 ``--data`` options.  ``XDG_CONFIG_HOME`` defaults to ``$HOME/.config``
 105 and ``XDG_DATA_HOME`` defaults to ``$HOME/.local/share``.
 106
 107 You should edit the default configuration file now to adjust rss2email
 108 for your local system.  Unless you've installed a local
 109 sendmail-equivalent, you'll need to edit the SMTP_ options.
 110
 111 Subscribe to some feeds::
 112
 113   $ r2e add rss2email http://rss.gmane.org/gmane.mail.rss2email
 114
 115 That's the feed to be notified when there's a new version of
 116 rss2email. Repeat this for each feed you want to subscribe to.
 117
 118 When you run rss2email, it emails you about every story it hasn't seen
 119 before. But the first time you run it, that will be every story. To
 120 avoid this, you can ask rss2email not to send you any stories the
 121 first time you run it::
 122
 123   r2e run --no-send
 124
 125 Then later, you can ask it to email you new stories::
 126
 127   r2e run
 128
 129 Customizing rss2email
 130 =====================
 131
 132 There are a number of options, described in full in
 133 ``rss2email/config.py``, to customize the way rss2email behaves. If
 134 you want to change something, edit the the configuration file that was
 135 created by ``r2e new``.
 136
 137 For example, if you want to receive HTML mail, instead of having
 138 entries converted to plain text::
 139
 140   html-mail = True
 141
 142 To be notified every time a post changes, instead of just when it's
 143 first posted::
 144
 145   trust-guid = True
 146
 147 And to make the emails look as if they were sent when the item was
 148 posted::
 149
 150   date-header = True
 151
 152 If you get an error message ``Sender domain must exist``, add the
 153 following to your configuration file::
 154
 155   from = rss2email@yoursite.com
 156   force-from = True
 157
 158 You can make the email address whatever you want, but your mail server
 159 requires that the ``yoursite.com`` part actually exists.
 160
 161 SMTP
 162 ----
 163
 164 By default, rss2email uses sendmail (or an equivalent) to send
 165 outgoing email.  If you don't have such a program installed, or simply
 166 prefer to use SMTP__ directly, edit the configuration file and fill in
 167 your outoing email server's details::
 168
 169   [DEFAULT]
 170   ...
 171   use-smtp = True
 172   smtp-server = smtp.yourisp.net:587
 173   smtp-auth = False
 174   ...
 175
 176 If your server requires you to login, change ``smtp-auth = False`` to
 177 ``smtp-auth = True`` and enter your email username and password::
 178
 179   smtp-auth = True
 180   smtp-username = username
 181   smtp-password = password
 182
 183 If your server requires an `TLS/SSL`_ connection (SMTPS), change
 184 ``smtp-ssl = False`` to ``smtp-ssl = True``.  If your server does
 185 not require a SMTPS connection but you request authentication,
 186 rss2email will use STARTTLS_ to encrypt the connection before sending
 187 your login credentials to the server.
 188
 189 __ `Simple Mail Transport Protocol`_
 190
 191 Automating rss2email
 192 ====================
 193
 194 More than likely you will want rss2email to run automatically at a
 195 regular interval. Under Windows this is can be easily accomplished
 196 using the Windows Task Scheduler. This site has a
 197 nice tutorial__ on it. Just select ``r2e.bat`` as the program to run. Once
 198 you've created the task, double click on it in the task list and
 199 change the Run entry so that ``run`` comes
 200 after ``r2e.bat``. For example, if you installed rss2email in
 201 the ``C:\rss2email`` directory, then you would change the Run
 202 entry from ``C:\rss2email\r2e.bat``
 203 to ``C:\rss2email\r2e.bat run``.
 204
 205 __ `windows scheduler`_
 206
 207 On Unix/Linux systems, you should add a cron_ job that runs ``r2e``.
 208 For example, run ``r2e`` every night (at 1:23 am) with::
 209
 210   23 1 * * * r2e run
 211
 212 Development
 213 ===========
 214
 215 User discussion and development take place on the rss2email mailing
 216 list at ``rss2email@tremily.us``.  Everyone is welcome to post bug
 217 reports, feature requests, comments, and patches.  To subscribe to the
 218 list, send an email to ``rss2email+subscribe@tremily.us``.  The
 219 mailing list archives are available on Gmane_.
 220
 221
 222 .. _Debian package:
 223   http://packages.qa.debian.org/r/rss2email.html
 224 .. _Ubuntu package:
 225   https://launchpad.net/ubuntu/+source/rss2email
 226 .. _openSUSE package:
 227   https://build.opensuse.org/package/show?package=rss2email&project=server%3Amail
 228 .. _NetBSD package:
 229   ftp://ftp.netbsd.org/pub/NetBSD/NetBSD-current/pkgsrc/mail/rss2email/README.html
 230 .. _Gentoo package:
 231   http://gpo.zugaina.org/net-mail/rss2email
 232 .. _Python: http://www.python.org
 233 .. _feedparser: http://pypi.python.org/pypi/feedparser
 234 .. _html2text: http://pypi.python.org/pypi/html2text
 235 .. _Git: http://git-scm.com/
 236 .. _Simple Mail Transport Protocol: http://en.wikipedia.org/wiki/Simple_Mail_Transport_Protocol
 237 .. _TLS/SSL: http://en.wikipedia.org/wiki/Transport_Layer_Security
 238 .. _STARTTLS: http://en.wikipedia.org/wiki/STARTTLS
 239 .. _windows scheduler: http://www.iopus.com/guides/winscheduler.htm
 240 .. _cron: http://en.wikipedia.org/wiki/Cron
 241 .. _Gmane: http://dir.gmane.org/gmane.mail.rss2email