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