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`` and ``~/.local/share``),
  90 there is no 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 (``$XDG_CONFIG_HOME/rss2email.cfs`` by default) and a feed database
 101 (``$XDG_DATA_HOME/rss2email.json`` by default).  If you'd rather those
 102 files were stored in other locations, use the ``--config`` and
 103 ``--data`` options.  ``XDG_CONFIG_HOME`` defaults to ``$HOME/.config``
 104 and ``XDG_DATA_HOME`` defaults to ``$HOME/.local/share``.
 105
 106 You should edit the default configuration file now to adjust rss2email
 107 for your local system.  Unless you've installed a local
 108 sendmail-equivalent, you'll need to edit the SMTP_ options.
 109
 110 Subscribe to some feeds::
 111
 112   $ r2e add rss2email http://rss.gmane.org/gmane.mail.rss2email
 113
 114 That's the feed to be notified when there's a new version of
 115 rss2email. Repeat this for each feed you want to subscribe to.
 116
 117 When you run rss2email, it emails you about every story it hasn't seen
 118 before. But the first time you run it, that will be every story. To
 119 avoid this, you can ask rss2email not to send you any stories the
 120 first time you run it::
 121
 122   r2e run --no-send
 123
 124 Then later, you can ask it to email you new stories::
 125
 126   r2e run
 127
 128 Customizing rss2email
 129 =====================
 130
 131 There are a number of options, described in full in
 132 ``rss2email/config.py``, to customize the way rss2email behaves. If
 133 you want to change something, edit the the configuration file that was
 134 created by ``r2e new``.
 135
 136 For example, if you want to receive HTML mail, instead of having
 137 entries converted to plain text::
 138
 139   html-mail = True
 140
 141 To be notified every time a post changes, instead of just when it's
 142 first posted::
 143
 144   trust-guid = True
 145
 146 And to make the emails look as if they were sent when the item was
 147 posted::
 148
 149   date-header = True
 150
 151 If you get an error message ``Sender domain must exist``, add the
 152 following to your configuration file::
 153
 154   from = rss2email@yoursite.com
 155   force-from = True
 156
 157 You can make the email address whatever you want, but your mail server
 158 requires that the ``yoursite.com`` part actually exists.
 159
 160 SMTP
 161 ----
 162
 163 By default, rss2email uses sendmail (or an equivalent) to send
 164 outgoing email.  If you don't have such a program installed, or simply
 165 prefer to use SMTP__ directly, edit the configuration file and fill in
 166 your outoing email server's details::
 167
 168   [DEFAULT]
 169   ...
 170   use-smtp = True
 171   smtp-server = smtp.yourisp.net:587
 172   smtp-auth = False
 173   ...
 174
 175 If your server requires you to login, change ``smtp-auth = False`` to
 176 ``smtp-auth = True`` and enter your email username and password::
 177
 178   smtp-auth = True
 179   smtp-username = username
 180   smtp-password = password
 181
 182 If your server requires an `TLS/SSL`_ connection (SMTPS), change
 183 ``smtp-ssl = False`` to ``smtp-ssl = True``.  If your server does
 184 not require a SMTPS connection but you request authentication,
 185 rss2email will use STARTTLS_ to encrypt the connection before sending
 186 your login credentials to the server.
 187
 188 __ `Simple Mail Transport Protocol`_
 189
 190 Automating rss2email
 191 ====================
 192
 193 More than likely you will want rss2email to run automatically at a
 194 regular interval. Under Windows this is can be easily accomplished
 195 using the Windows Task Scheduler. This site has a
 196 nice tutorial__ on it. Just select ``r2e.bat`` as the program to run. Once
 197 you've created the task, double click on it in the task list and
 198 change the Run entry so that ``run`` comes
 199 after ``r2e.bat``. For example, if you installed rss2email in
 200 the ``C:\rss2email`` directory, then you would change the Run
 201 entry from ``C:\rss2email\r2e.bat``
 202 to ``C:\rss2email\r2e.bat run``.
 203
 204 __ `windows scheduler`_
 205
 206 On Unix/Linux systems, you should add a cron_ job that runs ``r2e``.
 207 For example, run ``r2e`` every night (at 1:23 am) with::
 208
 209   23 1 * * * r2e run
 210
 211 Development
 212 ===========
 213
 214 User discussion and development take place on the rss2email mailing
 215 list at ``rss2email@tremily.us``.  Everyone is welcome to post bug
 216 reports, feature requests, comments, and patches.  To subscribe to the
 217 list, send an email to ``rss2email+subscribe@tremily.us``.  The
 218 mailing list archives are available on Gmane_.
 219
 220
 221 .. _Debian package:
 222   http://packages.qa.debian.org/r/rss2email.html
 223 .. _Ubuntu package:
 224   https://launchpad.net/ubuntu/+source/rss2email
 225 .. _NetBSD package:
 226   ftp://ftp.netbsd.org/pub/NetBSD/NetBSD-current/pkgsrc/mail/rss2email/README.html
 227 .. _Gentoo package:
 228   http://gpo.zugaina.org/net-mail/rss2email
 229 .. _Python: http://www.python.org
 230 .. _feedparser: http://pypi.python.org/pypi/feedparser
 231 .. _html2text: http://pypi.python.org/pypi/html2text
 232 .. _Git: http://git-scm.com/
 233 .. _Simple Mail Transport Protocol: http://en.wikipedia.org/wiki/Simple_Mail_Transport_Protocol
 234 .. _TLS/SSL: http://en.wikipedia.org/wiki/Transport_Layer_Security
 235 .. _STARTTLS: http://en.wikipedia.org/wiki/STARTTLS
 236 .. _windows scheduler: http://www.iopus.com/guides/winscheduler.htm
 237 .. _cron: http://en.wikipedia.org/wiki/Cron
 238 .. _Gmane: http://dir.gmane.org/gmane.mail.rss2email