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