rss2imap - How to use Documentation

Requirements

Required softwares to use rss2imap are as follows:

Perl 5.8.0 or later（required）
Perl modules
- Mail::IMAPClient
- Encode
- XML::Parser
- XML::RSS
- LWP (LWP::UserAgent, LWP::Simple)
- Jcode
- IO::Socket::SSL(required in case of using IMAP over SSL).
- Digest::HMAC
A host which is running an IMAP server (checked on dovecot and courier-imap).
Working reports of other IMAP server (e.g., Binc IMAP) are welcomed. :-)
An IMAP-enabled mailer (Mozilla Thunderbird, Outlook Express, Becky!, Sylpheed, or so).
An inline HTML-rendering supported mailer (optional for HTML mode)
Mozilla Thunderbird, Outlook Express, Becky!, etc.

rss2imap might be worked on most of UNIX.
Windows support is working in progress.

Install

Install perl modules mentioned in the Requirements on your system.
```
perl -MCPAN -e shell
cpan> install Mail::IMAPClient
....
```
Download rss2imap following the download instruction.
Extract downloaded rss2imap package anywhere on your system, and move to the directory.
```
tar xvfz rss2imap-xxxx.tar.gz
cd rss2imap-xxxx
```
Edit conf/rss2imap.conf to configure connection setting to IMAP server. Note that the configuration file is written in UTF-8 (conf/rss2imap-site.conf is same as well). configure properly accordind to the explanation on the file.
Then, edit conf/rss2imap-site.conf to configure mail delivery. configure properly according to the explanation on the file. In most cases, there is no need to change default setting except "from" and "to".

Getting Started

First of all, let's run rss2imap using sample RSS URL list included in the package. Note that preventing deamonization using option -o.

./rss2imap -o sample.url

rss2map will be successfully launched if your connection preference configured on installation is correct.

* Check your conf/rss2imap.conf if rss2imap raises "Authentication Failure" or "imap client initialize failed".

Access to the IMAP server using your mailer. Folder that its name is prefixed by "RSS" should be created. You should be received articles.

most of settings set up rss2imap.conf and rss2imap-site.conf are able to override by command line option. Detailed option usage is available by "./rss2imap --help."

Here are the examples running rss2imap with command line option.

In case of using courier-imap (changes prefix to INBOX)

./rss2imap -o -s IMAP-server -u username -p INBOX sample.url

If you use dovecot, you can leave prefix value nil.(This is default)
```
./rss2imap -o -s [IMAP Server] -u [User Name] sample.url
```
In case of using IMAP over SSL, use -S option. You should change port number with -P option.
```
./rss2imap -o -s [IMAP Server] -S -P 993 -u [User Name] sample.url
```

When you authenticate yourseld by CRAM-MD5, use -c option.

./rss2imap -c -s [IMAP Server] -u [User Name] sample.url

If you run rss2imap with Debug mode(with -D option), it prints interaction with IMAP Server.
```
./rss2imap -D -s [IMAP Server] -u [User Name] sample.url
```

The sample.url file described in Getting Started is called "RSS site list", in which you write RSS uri, folder name of a mail destination folder, and so on. More than one "RSS site list" is required to run rss2imap.

How to edit this file is described as follows.

You must write rss site info in the configuration file. Please make appropriate site group in accordance with the nature of site. Site group has unique configuration value and list of RSS URL. You MUST write one or more blank line between every group.

# Configuration GROUP 1
Configuration 1: value 1
Configuration 2: value 2
..
http://foo1/foo.rdf
http://bar1/bar.rdf

# Configuration GROUP 2
Configuration 1: value 1
Configuration 2: value 2
..
http://foo2/foo.rdf
http://bar2/bar.rdf

Configuration items are as follows.

Configuration name	Condition of value	Description
folder	Folder name	IMAP folder name. rss2imap delivers mail to this folder. The defaul value is "RSS.%{channel:title}", which generate folder name dynamically by using macros described later.
type	(items\|channel)	items: rss2imap send every item of RDF as one mail.(Default) channel: rss2imap ignores every rss item and send ENTIRE RDF(channel) as one mail. You can use "channel" if you want to know if web site is updated.
sync	(yes\|no)	yes: rss2imap sync mails in folder with RSS items. it deletes mail that does not exist in RSS feed. no: does not sync with rss items.(Default)
expire	Integer (N)	Delete item which are "N" days before. You can limit this behavior by specifying this value as -1. (Default)
expire-unseen	(yes\|no)	yes: rss2imap deletes unread mail when rss item is expired. no: Does not delete unread mail.(Default)
expire-folder	folder name	rss2imap moves expired mail to the specified folder. if this value is not specified, rss2imap deletes expired item. You can use macros which are described later.
subject	String	Specify "subject:" header. You can usually leave this value as default. You can use macros which are described later.
from	String	Specify "From:" header. You can usually leave this value as default. You can use macros which are described later.

You can specify configuration values by using macro, which can generate values of "folder", "expire-folder", "subject", "from" from contents of rss dynamically.
Macro lists are as follows. Every Macro is replaced with correlating value.

Macro Name	Description
%{host}	Hostname
%{user}	Username
%{rss-link}	RSS URL
%{last-modified}	Last-Modifed header which web server returns.
%{item:link}	Link value of every RSS item.
%{item:title}	Title of every RSS item.
%{item:description}	Description of every RSS item
%{item:dc:date}	dc:date of every RSS item.(undefined in some RSS)
%{item:dc:subject}	dc:subject of every RSS item.(undefined in some RSS)
%{item:dc:creator}	dc:creator of every RSS item.(undefined in some RSS)
%{channel:link}	Link of RSS channel.
%{channel:title}	Title of RSS channel.
%{channel:description}	Description of RSS channel.
%{channel:dc:date}	dc:date of RSS channel. (undefined in some RSS)

However, if you specify "type: channel" value, the value of %{item:*} and %{channel:*} are same.

Default value is as follows.

subject:   %{item:title}
from:      <%{channel:title}>

For example, description as follows generates imap folder by using channel title.

folder: RSS.News.%{channel:title}

Examples of RSS Site List are as follows.

# Hatena Antena(http://a.hatena.ne.jp/).
# You sync contents of Antena with mails in folder "RSS.Anntena"
folder: RSS.Anntena
expire: 3
sync: yes
http://a.hatena.ne.jp/foo/rss

# separete Blog entry by every feed.
# Friend's Blog Feed.
folder: RSS.Blog.Friend
expire: 5
http://tahoo.org/~taku/diary/cl.rdf
http://nais.to/~yto/clog/cl.rdf

# IT releated feeds.
folder: RSS.Blog.IT
expire: 10
http://blog.japan.cnet.com/umeda/index.rdf
http://kimuratakeshi.cocolog-nifty.com/blog/index.rdf

# I want to know modified time of my own wiki.
# by "type: channel", rss2imap run as simple Antenna.
folder: RSS.Wiki
type: channel
http://tahoo.org/~taku/wiki/wiki.cgi?action=RSS
http://cl.naist.jp/index.php?cmd=rss

# rss2imap generates folder name from title of the news site.
# it leave articles of last two days and deletes entries before
# last two days, even if these are unread.
folder: RSS.News.%{channel:title}
expire: 2
expire-unseen: yes
http://www.atmarkit.co.jp/rss/rss2dc.xml
http://www3.asahi.com/rss/index.rdf
http://japan.cnet.com/rss/index.rdf
http://japan.linux.com/japanlinuxcom.rdf
http://slashdot.jp/slashdotjp.rss

Importing RSS site lists

To use rss2imap, more than one RSS site list is required, but it is some complicated task to edit this file. To reduce this complexity, you can import RSS site list from opme file with rss2imap. This functionality is useful for those who migrate from other RSS reader.

To import RSS site List from opml, enter the command as follows. You specify opml file with -I option, and file name of RSS site list with -O option.

./rss2imap -I foo.opml -O output.url

In output file with -I option, the configuration value is specified by the value of conf/rss2imap-site.conf, and the root of the folder name is "RSS".

Exporting to opml file

rss2imap have functionality which can export RSS site list as an opml file. You can this functionality to output general file format in other RSS reader.

To export RSS site list, enter the command as follows. You specify RSS site list file with -E option, and output file name with -O option.

./rss2imap -E bar.url -O output.opml

Text delivery mode and HTML delivery mode

rss2imap can deliver mail with two format, "text delivery mode" which delivers text/plain mail and "HTML delivery mode" which delivers text/html mail.

HTML delivery mode is useful whe you read mail with MUA which have functionality of the HTML inline presentaion. Whereas in text delivery mode, rss2imap can deliver text/plain mail for those who dislike text/html mail. You can see differences between these modes in screenshot page.

You can configure delivery mode by setting "delivery-mode" value in conf/rss2imap.conf, and can override its value with command line option "-d". (An Example comman of text delivery mode is as follows).

./rss2imap -d text -o sample.url

Currently HTML delivery mode is default mode, because text delivery is newly implemented and experimental.

Daemonize

If you found rss2imap works fine, you can daemonize it to run on regular basis. Run rss2imap without "-o" option.

./rss2imap sample.url

rss2imap update mail in every 60 minutes by default. In case of change update interval, you can use "-i" option. (an example of updating in every 30 minites is as follows)

./rss2imap -i 30 sample.url

rss2imap read "RSS site list" every time it starts to delivery mail, so its not a problem for you to change "RSS site list" in running rss2imap.

Special Folder

rssimap creates special folder as "RSS.last-modified".
rss2imap saves last-modified time of every rss as one mail in this special folder to reduce needless update process.

If you want to force rss2imap to update, please delete these mail.

If you change special folder name, specify it with "-m" option.

./rss2imap -m FOO.BAR.RSS.last-modified

reversethis -> {gro} {tod} {umumum} {ta} {umumum}

rss2imap - Documentation