Added summary and more detailed instructions for the spell checker
[claws.git] / README.claws
1 README.claws
2 ------------
3
4 Summary:
5
6 1. What is Sylpheed Claws?
7 2. Switching to Claws
8 3. Things Claws does different
9    * auto address replacement in summary view
10    * manual selection of MIME types for attachments
11    * sharing mail folders
12    * default to address for folders
13    * threading mode per folder
14    * quotation wrapping
15    * spell checking (with installation instructions)
16 4. How to contribute
17 5. How to request features
18
19 1. What is Sylpheed Claws?
20 --------------------------
21
22 Sylpheed Claws is a bleeding edge branch of Sylpheed, a light weight mail 
23 user agent for UNIX. Features in this branch may (or may not) end up in 
24 Sylpheed. 
25
26 Hiroyuki's ChangeLog is also included in the claws-branch distribution, 
27 so it should be easy to spot which features were merged with Sylpheed
28 (and which features were not).
29
30 For brevity Sylpheed Claws is referred to as Claws, and Sylpheed as either
31 Sylpheed or Main.
32
33
34 2. Switching to Claws
35 ---------------------
36
37 From the user perspective Claws is just a fancy Sylpheed, so it uses the
38 same sylpheed setting files located in ~/.sylpheed.
39
40 It's always a good idea to back up all files in ~/.sylpheed in case
41 you want to switch back to Sylpheed. (You don't have to backup the
42 directories.)
43
44 There are some things that frequently come up when switching to Claws:
45
46
47 * When replying, the original sender's text is not quoted anymore.
48
49   Claws has a different quote format handler. Add either %Q or %q to the
50   quote format text. Also click the button "Description of symbols"
51   for more quotation symbols.
52
53
54 * Why does the advanced filtering system not work?
55
56   Claws uses the new filtering system as soon as you define a new rule for it.
57   Your old sylpheed filter rules will not be used. In subdirectory tools/ of
58   the distribution there is a Perl script called filter_conv.pl which convers
59   old filter rules to the claws filtering system.
60   
61
62 * What happened to the compose email and compose news buttons? 
63
64   There's a composite button for both composing mail and news. You can toggle
65   between composing mail and news by clicking on the button with the triangle.
66
67
68 * And to the Preferences and Execute buttons?
69
70   Sorry, they're not there.
71
72
73
74 3. Things Claws does different
75 ------------------------------
76
77 Claws does a lot of things different. Here a quick run-down of things that
78 are hardly noticable, but deserve mentioning:
79
80 * auto address replacement in summary view
81   This matches a plain email address with a person in the address book. This
82   feature is enabled in Common Preferences | Tab Display | SummaryView Group |
83   Display sender using addressbook
84
85 * manual selection of MIME types for attachments
86   You can change the MIME type of an attachment by right-clicking in the
87   attachment list, selecting Property in the menu. The MIME type list
88   is a combo box with the known MIME types.
89
90 * sharing mail folders   
91   You can also share or use shared mail folders. Right-click a folder and
92   select Property. Change the Folder chmod setting.
93
94 * default to address for folders
95   Most people filter mailing list mails to separate folders. Claws allows
96   you to associate a folder with a mailing list or a person. Right-click a
97   folder, select Property and change the Default To setting. When you
98   compose a new mail, when this folder is selected the recepient address
99   will be set to this address.
100
101   (NOTE: this is also a shoot-yourself-in-the-foot-setting! If you want
102    to send a private mail, don't have a folder selected with this setting
103    set.)
104
105 * threading mode per folder
106   Folders can have their own threading and sorting mode. Just select a 
107   folder, and set their threading and sorting mode.
108
109
110 * quotation wrapping
111   Quotation is wrapped like VIM would wrap it (at least that was the
112   goal). To enable this feature go to Common preferences->Compose and
113   make sure Wrap quotation is enabled. The text is automatically
114   wrapped when you reply to an e-mail if this feature is enabled.
115
116 * Spell checker for Sylpheed-Claws
117   
118   a. Requirements
119   b. Configuration and installation
120   c. Usage
121   d. Known problems
122
123   a. Requirements
124   ---------------
125
126   The spell checker in sylpheed requires the Portable Spell Checker
127   Interface Library pspell (http://pspell.sourceforge.net), version
128   0.12.2 or newer.
129
130   You will need also the actual spell checker.  There are two alternatives:
131
132      i) ispell (http://fmg-www.cs.ucla.edu/fmg-members/geoff/ispell.html),
133         which is found on quasi every distribution.  You have then to
134         install the pspell-ispell module found at the pspell site.
135
136     ii) aspell (http://aspell.sourceforge.net).  This spell checker
137         must be installed after installing pspell.  The version tested
138         is .33.7 alpha. It has three different suggestion modes (fast
139         -default- , normal, bad spellers), has the ability to learn
140         from mistakes (default). 
141
142   And, last but not least, do not forget to install the dictionaries. Check
143   the corresponding spell checker home page for more information on this.
144
145   b. Configuring Sylpheed
146   -----------------------
147
148   Spell checking is enabled if you configure sylpheed appropriately. Add
149   the option '--enable-pspell' when configuring. E.g.:
150
151   ./configure --enable-pspell
152
153   The configure script needs 'pspell-config' in your path.  If it is
154   in weird places, use '--with-pspell-prefix' to tell the path to
155   pspell-config.  E.g., if pspell-config is really
156   /foo/bar/pspell-config, then use:
157
158   ./configure --enable-pspell --with-pspell-prefix=/foo/bar
159
160   If you have problems with not found includes or libraries, check
161   first where these are located, and add either options:
162
163   --with-pspell-includes=/foo/bar/include
164
165   or 
166
167   --with-pspell-libs=/foo/bar/lib
168
169   as appropriate.
170
171   Configure script summarizes the options compiled in. Check that
172   configure lists 'Pspell = yes'.
173
174   Then proceed as usual, with 'make' and 'make install'.
175
176   c. Usage
177   --------
178
179   After successful compiling, you need to tell sylpheed where your
180   dictionaries reside.  First run 'pspell-config pkgdatadir' on the
181   shell to get their path.
182
183   Then run sylpheed and go to Configuration -> Common preferences ->
184   Compose.  Check the box 'Enable spell checker (EXPERIMENTAL)' and
185   use the file selector ('...' button) to select the path where the
186   dictionaries reside.  Within the file selector, go to that directory
187   and select *any* file in the file lists.  Click ok. You should then
188   be able to select your default dictionary.
189
190   When composing, misspelled words are highlighted.  Click on any
191   highlighted word with the right mouse button to get a list of
192   suggestions.  You can also accept the highlighted word to the
193   session dictionary (equivalent to an 'ignore' option of other spell
194   checker), or you can add it to you personal dictionary.
195
196   If you click with the right mouse button everywhere else, or if you
197   shift-right-click even on a misspelled word, you get the
198   configuration  menu.  'Check all' highlights all misspelled words.
199   With this menu, you can also change the dictionary while editing.
200   You can change the suggestion mode and toggle the learn from
201   misktakes 'feature' (useful only with aspell).
202
203   d. Known problems
204   -----------------
205
206     i) libtool
207
208     The only real known problems until now are configuration and
209     compilation problems  due to libtool interaction with pspell. 
210
211     If you do not compile pspell/aspell/pspell-ispell yourself, you
212     need to install them with their devel packages.
213
214     Pspell work with dynamic linking of libraries and thus uses the
215     libltdl library of libtool.  If you have weird problems when
216     configuring showing 'libtool', chances are the libtool used when
217     compiling the pspell package is not compatible with what you have
218     on your system.  The best solution, is to install the latest
219     libtool AND compile yourself pspell package.  I can't help more
220     than that in this issue.
221
222     After successfully compiled and used sylpheed with spell checking,
223     the same problem can appear if you upgrade your libtool to a
224     version which libltdl is incompatible to your older one.    The
225     symptoms are a crash when starting to compose.  Disabling spell
226     checking avoids the problem. The solution should be to recompile pspell.
227
228     ii) New installed ispell dictionary are not detected
229
230     Installing a new ispell dictionary needs an additional step. Go
231     to the 'pkgdatadir' and run 'make-ispell-pwli'.  You may need to
232     su root.
233
234
235 There are a lot more options. If you find one, don't hesitate to
236 mention it.
237
238
239 4. How to contribute
240 --------------------
241
242 Sylpheed Main: 
243
244         submit it to the Sylpheed ML, Hiroyuki, or Paul Mangan
245         (for incorporation on the Sylpheed Patches page)
246
247 Sylpheed Claws:
248
249         It is highly recommended to use the sourceforge project page
250         of claws. Check: 
251         http://sourceforge.net/tracker/?atid=384600&group_id=25528&func=browse
252
253         If that's too troublesome, either contact Paul Mangan or consider
254         posting to the sylpheed claws users mailing list.
255
256         Bugs can be reported in the same way; the recommended web page:
257         http://sourceforge.net/tracker/?group_id=25528&atid=384598
258
259         Ofcourse you can also post to the sylpheed claws users
260         mailing list.
261
262 Also, we really try to incorporate good contributions, but sometimes we
263 don't have enough time. If the contribution is really big, or requires
264 a long time to stabilize, send a mail to Paul Mangan. We can probably
265 arrange access to the Claws branch.
266
267
268 5. How to request features
269 --------------------------
270
271 Ask around in both Sylpheed ML and Sylpheed Claws Users ML. Note
272 that some developers may already thought about your feature, may
273 perhaps be implementing it - or the feature was already discussed
274 and rejected for whatever reason.  You might want to go ahead and 
275 hack a patch for it. (That would be very cool!) Another
276 possibility is to use the Feature Request Tracker at the
277 sourceforge project page.