--- /dev/null
+.. -*- coding: utf-8 -*-
+
+==============================
+Getting Started With rss2email
+==============================
+
+We highly recommend that you subscribe to the rss2email project feed
+so you can keep up to date with the latest version, bugfixes and
+features:
+
+ http://feeds.feedburner.com/allthingsrss/hJBr
+
+.. contents::
+
+Installing rss2email
+====================
+
+Packages
+--------
+
+A quick way to get rss2email going is using pre-made packages. Here
+are releases for Debian__ Linux, Ubuntu__ Linux, Gentoo__ Linux, and
+NetBSD__.
+
+__ `Debian package`_
+__ `Ubuntu package`_
+__ `Gentoo package`_
+__ `NetBSD package`_
+
+Installing by hand
+------------------
+
+Requirements
+~~~~~~~~~~~~
+
+Before you install rss2email, you'll need to make sure that a few
+things are in place.
+
+1. Ensure that a version of Python_ ≥3.2 is installed.
+2. Install the required Python packages.
+
+ 1. feedparser_
+ 2. html2text_
+
+3. Figure out how you are going to send outgoing email. You have two
+ options here: either use an STMP server or a local sendmail
+ program. So,
+
+ * determine your outgoing email server's SMTP address, or
+ * install sendmail (or a compatible replacement like postfix).
+
+Download
+~~~~~~~~
+
+Download the latest rss2email source and unpack it. You can choose
+from several equivalent formats.
+
+1. A ``.zip`` file (suggested for Microsoft Windows users)::
+
+ $ wget http://www.allthingsrss.com/rss2email/rss2email-2.71.zip
+ $ unzip rss2email-*.zip
+
+2. A ``.tar.gz`` file (suggested for everyone else)::
+
+ $ wget http://www.allthingsrss.com/rss2email/rss2email-2.71.tar.gz
+ $ tar xvf rss2email*.tar.gz
+
+3. A Git_ checkout (suggested for developers)::
+
+ $ git clone git://tremily.us/rss2email.git
+
+Install
+~~~~~~~
+
+From the unpacked directory, run::
+
+ $ python setup.py install
+
+You can pass all the usual options to the ``install`` command,
+including ``--user``. If you don't want to install rss2email, you can
+also run ``r2e`` directly from the source directory.
+
+Upgrading to a new version
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Just repeat the installation procedure for the new source package. If
+your config file and data file were in the old source directory, move
+them over to the new source directory. If the config and data files
+were in another directory (e.g. ``~/.config/rss2email/``), there is no
+need to move them.
+
+Using rss2email
+===============
+
+Create a new feed database to send updates to your email address::
+
+ $ r2e new you@yourdomain.com
+
+This command will create a configuration file
+(``~/.config/rss2email/config`` by default) and a feed database
+(``~/.config/rss2email/feeds.dat`` by default). If you'd rather those
+files were stored in other locations, use the ``--config`` and
+``--data`` options.
+
+You should edit the default configuration file now to adjust rss2email
+for your local system. Unless you've installed a local
+sendmail-equivalent, you'll need to edit the SMTP_ options.
+
+Subscribe to some feeds::
+
+ $ r2e add rss2email http://feeds.feedburner.com/allthingsrss/hJBr
+
+That's the feed to be notified when there's a new version of
+rss2email. Repeat this for each feed you want to subscribe to.
+
+When you run rss2email, it emails you about every story it hasn't seen
+before. But the first time you run it, that will be every story. To
+avoid this, you can ask rss2email not to send you any stories the
+first time you run it::
+
+ r2e run --no-send
+
+Then later, you can ask it to email you new stories::
+
+ r2e run
+
+Customizing rss2email
+=====================
+
+There are a number of options, described in full in ``rss2email.py``
+around line 270, to customize the way rss2email behaves. If you want
+to change something, edit the the configuration file that was created
+by ``r2e new``.
+
+For example, if you want to receive HTML mail, instead of having
+entries converted to plain text::
+
+ html-mail = True
+
+To be notified every time a post changes, instead of just when it's
+first posted::
+
+ trust-guid = True
+
+And to make the emails look as if they were sent when the item was
+posted::
+
+ date-header = True
+
+If you get an error message ``Sender domain must exist``, add the
+following to your configuration file::
+
+ from = rss2email@yoursite.com
+ force-from = True
+
+You can make the email address whatever you want, but your mail server
+requires that the ``yoursite.com`` part actually exists.
+
+SMTP
+----
+
+By default, rss2email uses sendmail (or an equivalent) to send
+outgoing email. If you don't have such a program installed, or simply
+prefer to use SMTP__ directly, edit the configuration file and fill in
+your outoing email server's details::
+
+ [DEFAULT]
+ …
+ use-smtp = True
+ smtp-server = smtp.yourisp.net:587
+ smtp-auth = False
+ …
+
+If your server requires you to login, change ``smtp-auth = False`` to
+``smtp-auth = True`` and enter your email username and password::
+
+ smtp-auth = True
+ smtp-username = username
+ smtp-password = password
+
+If your server requires an `TLS/SSL`_ connection (SMTPS), change
+``smtp-ssl = False`` to ``smtp-ssl = True``. If your server does
+not require a SMTPS connection but you request authentication,
+rss2email will use STARTTLS_ to encrypt the connection before sending
+your login credentials to the server.
+
+__ `Simple Mail Transport Protocol`_
+
+Automating rss2email
+====================
+
+More than likely you will want rss2email to run automatically at a
+regular interval. Under Windows this is can be easily accomplished
+using the Windows Task Scheduler. This site has a
+nice tutorial__ on it. Just select ``r2e.bat`` as the program to run. Once
+you've created the task, double click on it in the task list and
+change the Run entry so that ``run`` comes
+after ``r2e.bat``. For example, if you installed rss2email in
+the ``C:\rss2email`` directory, then you would change the Run
+entry from ``C:\rss2email\r2e.bat``
+to ``C:\rss2email\r2e.bat run``.
+
+__ `windows scheduler`_
+
+On Unix/Linux systems, you should add a cron_ job that runs ``r2e``.
+For example, run ``r2e`` every night (at 1:23 am) with::
+
+ 23 1 * * * r2e run
+
+
+.. _Debian package:
+ http://packages.debian.org/cgi-bin/search_packages.pl?searchon=names&version=all&exact=1&keywords=rss2email
+.. _Ubuntu package:
+ http://packages.ubuntu.com/search?keywords=rss2email&searchon=names§ion=all
+.. _NetBSD package:
+ ftp://ftp.netbsd.org/pub/NetBSD/NetBSD-current/pkgsrc/mail/rss2email/README.html
+.. _Gentoo package:
+ http://gpo.zugaina.org/net-mail/rss2email
+.. _Python: http://www.python.org
+.. _feedparser: http://pypi.python.org/pypi/feedparser
+.. _html2text: http://pypi.python.org/pypi/html2text
+.. _Git: http://git-scm.com/
+.. _Simple Mail Transport Protocol: http://en.wikipedia.org/wiki/Simple_Mail_Transport_Protocol
+.. _TLS/SSL: http://en.wikipedia.org/wiki/Transport_Layer_Security
+.. _STARTTLS: http://en.wikipedia.org/wiki/STARTTLS
+.. _windows scheduler: http://www.iopus.com/guides/winscheduler.htm
+.. _cron: http://en.wikipedia.org/wiki/Cron
+++ /dev/null
-<!DOCTYPE html>
-<html>
-<head>
-<title>Getting Started With rss2email</title>
-<style type="text/css">
-.hint {
- color: green;
-}
-
-strong {
- color: red;
-}
-
-pre,code {
- color: #900;
- font-family: monospace;
-}
-</style>
-</head>
-<body>
-<h1>Getting Started With rss2email</h1>
-
-<p class="hint">We highly recommend that you subscribe to the
-rss2email project feed so you can keep up to date with the latest
-version, bugfixes and features:
-<a href="http://feeds.feedburner.com/allthingsrss/hJBr">
-http://feeds.feedburner.com/allthingsrss/hJBr</a></p>
-
-<ul>
- <li><a href="#windows">Instructions for Windows Users</a></li>
- <li><a href="#unix">Instructions for UNIX Users</a></li>
- <li><a href="#usage">Using rss2email</a></li>
- <li><a href="#customize">Customizing rss2email</a></li>
-</ul>
-
-<h2 id="windows">Instructions for Windows Users</h2>
-
-<h3>Requirements</h3>
-
-<p>Before you install rss2email, you'll need to make sure that a few
-things are in place. First, is that a version
-of <a href="http://www.python.org">Python</a> 3.2 or greater
-installed. Second, determine your outgoing email server's
-address. That should be all you need.</p>
-
-<h3>Download</h3>
-
-<ol>
- <li>Create a new directory.</li>
- <li>Download the latest rss2email <code>.ZIP</code> file and unzip to
- the new directory.</li>
-</ol>
-
-<h3>Configure</h3>
-
-<p>Edit the configuration file and fill in your outoing email server's
-details. If your server requires you to login,
-change <code>smtp-auth = False</code> to <code>smtp-auth = True</code>
-and enter your email username and password.</p>
-
-<h3>Install</h3>
-
-<p>From the command line, change to the directory you created, and
-just run <code>r2e</code> from this directory. For basic usage
-guidelines, look <a href="#usage">here</a>.</p>
-
-<h3>Automating rss2email</h3>
-
-<p>More than likely you will want rss2email to run automatically at a
-regular interval. Under Windows this is can be easily accomplished
-using the Windows Task Scheduler. This site has a
-nice <a href="http://www.iopus.com/guides/winscheduler.htm">tutorial</a>
-on it. Just select <code>r2e.bat</code> as the program to run. Once
-you've created the task, double click on it in the task list and
-change the Run entry so that <code>run</code> comes
-after <code>r2e.bat</code>. For example, if you installed rss2email in
-the <code>C:\rss2email</code> directory, then you would change the Run
-entry from <code>C:\rss2email\r2e.bat</code>
-to <code>C:\rss2email\r2e.bat run</code>.</p>
-
-<p>Now jump down to the section on <a href="#customize">customizing
-rss2email</a> to your needs.</p>
-
-<h3>Upgrading to a new version</h3>
-
-<p>Simply replace all of the files in your install
-directory <strong>EXCEPT your config file</strong> with new versions
-from the <code>.ZIP</code> package.</p>
-
-<h2 id="unix">Instructions for UNIX/Linux Users</h2>
-
-<h3>Requirements</h3>
-
-<p>Before you install rss2email, you'll need to make sure that a few
-things are in place: a version
-of <a href="http://www.python.org">Python</a> ≥3.2 and sendmail
-(or a compatible replacement like postfix) installed. If sendmail
-isn't installed, determine your outgoing email server's address. That
-should be all you need.</p>
-
-<h3>Download</h3>
-
-<p>A quick way to get rss2email going is using pre-made packages. Here
-are releases for
-<a href="http://packages.debian.org/cgi-bin/search_packages.pl?searchon=names&version=all&exact=1&keywords=rss2email">Debian</a> Linux,
-<a href="http://packages.ubuntu.com/search?keywords=rss2email&searchon=names§ion=all">Ubuntu</a> Linux,
-and
-<a href="ftp://ftp.netbsd.org/pub/NetBSD/NetBSD-current/pkgsrc/mail/rss2email/README.html">NetBSD</a>.</p>
-
-<p>If you are unable to use these packages or you want the latest and
-greatest version, here's what you do:</p>
-
-<pre>
-$ tar xvf rss2email-*.tar.gz
-$ mv rss2email-* /path/to/install/location/
-$ cd /path/to/install/location
-$ chmod +x r2e
-</pre>
-
-<p>You can run <code>r2e</code> from this directory or add the
-installation directory to your <code>PATH</code>. For basic usage
-guidelines, look <a href="#usage">here</a>.</p>
-
-<h3>Upgrading to a new version</h3>
-
-<p>Simply replace all of the files in your install
-directory <strong>EXCEPT your config file</strong> with new versions
-from the <code>.tar.gz</code> package.</p>
-
-<h2 id="usage">Using rss2email</h2>
-
-</p>Create a new feed database to send updates to your email
-address:</p>
-
-<pre>
-r2e new you@yourdomain.com
-</pre>
-
-<p>Subscribe to some feeds:</p>
-
-<pre>
-r2e add rss2email http://feeds.feedburner.com/allthingsrss/hJBr
-</pre>
-
-<p>That's the feed to be notified when there's a new version of
-rss2email. Repeat this for each feed you want to subscribe to.</p>
-
-<p>When you run rss2email, it emails you about every story it hasn't
-seen before. But the first time you run it, that will be every
-story. To avoid this, you can ask rss2email not to send you any
-stories the first time you run it:</p>
-
-<pre>
-r2e run --no-send
-</pre>
-
-<p>Then later, you can ask it to email you new stories:</p>
-
-<pre>
-r2e run
-</pre>
-
-<p>If you get an error message <code>Sender domain must exist</code>,
-add a line to your configuration file like this:</p>
-
-<pre>
-DEFAULT_FROM = rss2email@yoursite.com
-</pre>
-
-<p>You can make the email address whatever you want, but your mail
-server requires that the <code>yoursite.com</code> part actually
-exists.</p>
-
-<h2 id="customize">Customize rss2email</h2>
-
-<p>There are a number of options, described in full at the top of
-<code>rss2email.py</code> file, to customize the way rss2email
-behaves. If you want to change something, edit the the configuration
-file. You may have to create this file if it doesn't already
-exist.</p>
-
-<p>For example, if you want to receive HTML mail, instead of having
-entries converted to plain text:</p>
-
-<pre>
-html-mail = True
-</pre>
-
-<p>To be notified every time a post changes, instead of just when it's
-first posted:</p>
-
-<pre>
-trust-guid = True
-</pre>
-
-<p>And to make the emails look as if they were sent when the item was
-posted:</p>
-
-<pre>
-date-header = True
-</pre>
-
-</body>
-</html>
projects / rss2email.git / commitdiff