From: W. Trevor King Date: Thu, 18 Oct 2012 14:45:17 +0000 (-0400) Subject: README: move readme.html -> README and convert to reStructuredText. X-Git-Tag: v3.0~72^2~15 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=97d66f82e03ba48f77a12ef8b257e6e758a5cda7;p=rss2email.git README: move readme.html -> README and convert to reStructuredText. This is in preparation for posting on PyPI. It is also easier to read rst source than it is to read HTML. You can generate an html version of the source with $ rst2html README > readme.html I also restructured the README to avoid separate Windows/UNIX sections, because almost all the advice applies to all systems. --- diff --git a/README b/README new file mode 100644 index 0000000..15e0b9b --- /dev/null +++ b/README @@ -0,0 +1,227 @@ +.. -*- 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 diff --git a/readme.html b/readme.html deleted file mode 100644 index da63e84..0000000 --- a/readme.html +++ /dev/null @@ -1,204 +0,0 @@ - - - -Getting Started With rss2email - - - -

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

- - - -

Instructions for Windows Users

- -

Requirements

- -

Before you install rss2email, you'll need to make sure that a few -things are in place. First, is that a version -of Python 3.2 or greater -installed. Second, determine your outgoing email server's -address. That should be all you need.

- -

Download

- -
    -
  1. Create a new directory.
    2. -
  2. Download the latest rss2email .ZIP file and unzip to - the new directory.
    3. -
- -

Configure

- -

Edit the configuration file and fill in your outoing email server's -details. If your server requires you to login, -change smtp-auth = False to smtp-auth = True -and enter your email username and password.

- -

Install

- -

From the command line, change to the directory you created, and -just run r2e from this directory. For basic usage -guidelines, look here.

- -

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.

- -

Now jump down to the section on customizing -rss2email to your needs.

- -

Upgrading to a new version

- -

Simply replace all of the files in your install -directory EXCEPT your config file with new versions -from the .ZIP package.

- -

Instructions for UNIX/Linux Users

- -

Requirements

- -

Before you install rss2email, you'll need to make sure that a few -things are in place: a version -of Python ≥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.

- -

Download

- -

A quick way to get rss2email going is using pre-made packages. Here -are releases for -Debian Linux, -Ubuntu Linux, -and -NetBSD.

- -

If you are unable to use these packages or you want the latest and -greatest version, here's what you do:

- -
-$ tar xvf rss2email-*.tar.gz
-$ mv rss2email-* /path/to/install/location/
-$ cd /path/to/install/location
-$ chmod +x r2e
-
- -

You can run r2e from this directory or add the -installation directory to your PATH. For basic usage -guidelines, look here.

- -

Upgrading to a new version

- -

Simply replace all of the files in your install -directory EXCEPT your config file with new versions -from the .tar.gz package.

- -

Using rss2email

- -

Create a new feed database to send updates to your email -address:

- -
-r2e new you@yourdomain.com
-
- -

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
-
- -

If you get an error message Sender domain must exist, -add a line to your configuration file like this:

- -
-DEFAULT_FROM = rss2email@yoursite.com
-
- -

You can make the email address whatever you want, but your mail -server requires that the yoursite.com part actually -exists.

- -

Customize rss2email

- -

There are a number of options, described in full at the top of -rss2email.py 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.

- -

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
-
- - -