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