1 .. -*- coding: utf-8 -*-
3 ==============================
4 Getting Started With rss2email
5 ==============================
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
11 http://rss.gmane.org/gmane.mail.rss2email
21 A quick way to get rss2email going is using pre-made packages. There
22 are releases for Debian__, Ubuntu__, Fedora__, openSUSE__, Gentoo__,
28 __ `openSUSE package`_
38 Before you install rss2email, you'll need to make sure that a few
41 1. Ensure that a version of Python_ ≥3.2 is installed.
42 2. Install the required Python packages.
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
51 * determine your outgoing email server's SMTP address, or
52 * install sendmail (or a compatible replacement like postfix).
57 Download the latest rss2email source and unpack it. You can choose
58 from several equivalent formats.
60 1. A ``.zip`` file (suggested for Microsoft Windows users)::
62 $ wget https://github.com/wking/rss2email/archive/v3.8.zip
63 $ unzip rss2email-*.zip
65 2. A ``.tar.gz`` file (suggested for everyone else)::
67 $ wget https://github.com/wking/rss2email/archive/v3.8.tar.gz
68 $ tar xvf rss2email*.tar.gz
70 3. A Git_ checkout (suggested for developers)::
72 $ git clone git://github.com/wking/rss2email.git
77 From the unpacked directory, run::
79 $ python setup.py install
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.
85 Upgrading to a new version
86 ~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
97 Create a new feed database to send updates to your email address::
99 $ r2e new you@yourdomain.com
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``.
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.
112 Subscribe to some feeds::
114 $ r2e add rss2email http://rss.gmane.org/gmane.mail.rss2email
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.
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::
126 Then later, you can ask it to email you new stories::
130 Customizing rss2email
131 =====================
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``.
138 For example, if you want to receive HTML mail, instead of having
139 entries converted to plain text::
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``)::
149 And to make the emails look as if they were sent when the item was
154 If you get an error message ``Sender domain must exist``, add the
155 following to your configuration file::
157 from = rss2email@yoursite.com
160 You can make the email address whatever you want, but your mail server
161 requires that the ``yoursite.com`` part actually exists.
163 You can also add custom filters, see the example and documentation in
164 ``rss2email/post_process/prettify.py`` for more information.
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::
177 smtp-server = smtp.yourisp.net:587
181 If your server requires you to login, change ``smtp-auth = False`` to
182 ``smtp-auth = True`` and enter your email username and password::
185 smtp-username = username
186 smtp-password = password
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.
194 __ `Simple Mail Transport Protocol`_
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``.
210 __ `windows scheduler`_
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::
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_.
228 http://packages.qa.debian.org/r/rss2email.html
230 https://launchpad.net/ubuntu/+source/rss2email
232 https://admin.fedoraproject.org/pkgdb/acls/name/rss2email
233 .. _openSUSE package:
234 https://build.opensuse.org/package/show?package=rss2email&project=server%3Amail
236 http://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc/mail/rss2email/README.html
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