Catch the exception if decoding failed.
[pymailheaders.git] / README
blobd63af9710eae1ba5d59a564df56e571e1d3cba85
1 Pymailheaders
2 =============
4 Pymailheaders is a small GTK+ program which displays mail headers in your mail
5 box.  It was innovated by xmailheaders, with a few more handy features like new
6 mail highlighting, multi-language support, lauching regardless of network
7 connection status and auto-reconnecting.  Pymailheaders was written from scratch
8 in Python for portability and easiness reasons.  IMAP4, POP3 protocols and XML
9 feeds are supported now.
11 If you find any bugs, you can either write me an "E-mail"
12 [mailto://zeegeek@gmail.com] or submit a bug report at "bug report page"
13 [http://sourceforge.net/tracker/?atid=929414&group_id=189460&func=browse].  For
14 feature requests, you can submit them at "feature request page"
15 [http://sourceforge.net/tracker/?atid=929417&group_id=189460&func=browse].
16 Thank you.
19 REQUIREMENTS
20 ============
22 You need the following packages install on your system in order to run
23 Pymailheaders,
25 * Python 2.4 (or above) [http://www.python.org/download/]
26 * PyGTK 2.6 (or above) [http://pygtk.org/downloads.html]
27 * GTK 2.6 (or above) [http://gtk.org/download/]
29 For *ubuntu users, all you need to do is to install python-gtk2 package.  And
30 then all the dependencies will be met by the package management system.  You can
31 simply type the following command in a terminal to get it done.
33 > sudo apt-get install python-gtk2 python-glade2 python-gobject
35 It should be similar in other distributions.
38 INSTALL
39 =======
41 You do not need to install this program, just run pymailheaders.py with
42 appropriate arguments.
45 USAGE
46 =====
48 Pymailheaders will look for a configuration file called .pymailheadersrc in your
49 home directory unless you use command line argument '-f' to specify another file
50 explicitly.  If you do not have a configuration file yet, Pymailheaders will
51 create one for you in your home directory.  If you already have one, you can
52 still use command line arguments to overwrite the options in the configuration
53 file.  If mandatory options like server type, server address, user name and
54 password are not provided in command line arguments nor in the configuration
55 file, Pymailheaders will tell you which options are missing.
57 Use 'pymailheaders.py -h' for full argument list.
59 On the first time running Pymailheaders, you have to provide all mandatory
60 options, namely server type, server address, user name and password (if
61 required), from the command line.
63 > pymailheaders.py -t imap -s express.cites.uiuc.edu -a -u zeegeek \
64   -p classified -e
66 After successfully launching Pymailheaders, you can omit all arguments except
67 for '-c' if you use another configuration file in future launches.  Everything
68 else can be set using Pymailheaders' GTK+ settings dialog by right clicking on
69 Pymailheaders' window.  Add a '&' mark at the end of the command to make it run
70 in background.
72 > pymailheaders.py
74 The following demonstrates how to run Pymailheaders for different protocols on command line.
76 For IMAP4 mailboxes, you need to set server type as imap and provide server URL,
77 username and password.  If your server supports encrypted connection, you also
78 have to set the ssl option.  The following example establishes a secured
79 connection with '-e' argument,
81 > pymailheaders.py -t imap -s express.cites.uiuc.edu -a -u zeegeek \
82   -p classified -e -i 60
84 To use pymailheaders with POP3 mailbox, it is basically the same as doing it
85 with IMAP4 mailbox.  The only thing you need to change is server type.  For
86 example,
88 > pymailheaders.py -t pop -s express.cites.uiuc.edu -a -u zeegeek \
89   -p classified -e -i 60
91 If you have a Gmail account and you want to check for new mails, just set server
92 type to feed and server to gmail.  Then you need to give your username and
93 password.  Here is an example,
95 > pymailheaders.py -t feed -s gmail -a -u zeegeek -p classified -i 60
97 You can also use pymailheaders to check for XML feeds in the formats of RSS 1.0,
98 2.0 and Atom 0.3, 1.0.  If your feed provider does not require authentication,
99 you do not need to provide username and password.  Example,
101 > pymailheaders.py -t feed -s http://feedparser.org/docs/examples/atom10.xml
104 SCREENSHOT
105 ==========
107 * Pymailheaders running in KDE [pymailheaders.png]
108 * Pymailheaders' settings dialog [settings.png]
111 DOWNLOAD
112 ========
114 * Pymailheaders - stable version [http://sourceforge.net/project/platformdownload.php?group_id=189460]
115 * Pymailheaders - development snapshot [http://repo.or.cz/w/pymailheaders.git?a=snapshot;h=HEAD;sf=tgz]
117 I'm not keeping the under-development code in SourceForge's Subversion
118 repository any more.  All the code has been moved to a "GIT repository"
119 [http://repo.or.cz/w/pymailheaders.git].
122 LINKS
123 =====
125 * Chinese Homepage [http://ning.appspot.com/pymailheaders/zh]
126 * Project Page [http://www.sourceforge.net/projects/pymailheaders]
127 * Code Repository [http://repo.or.cz/w/pymailheaders.git]
128 * My Homepage [http://www.zeegeek.cn]
129 * My Blog [http://eblog.zeegeek.cn]
130 * My Chinese Blog [http://blog.zeegeek.cn]