ff8cc05b0df37bd23063a497d49ab12add780ab8
[claws.git] / manual / advanced.xml
1 <?xml version="1.0" encoding="utf-8"?>
2 <section id="ch_advanced">
3   <title>Advanced features</title>
4   <section id="adv_actions">
5     <title>Actions</title>
6     <para>
7         Actions allow you to use all the power of the Unix command-line with 
8         your emails. You can define various commands, taking parameters such 
9         as the current email file, a list of emails, the currently selected 
10         text, and so on. In this way, you'll be able to perform various tasks
11         such as editing a raw mail in your text editor, 
12         <emphasis>hide</emphasis> what you mean using ROT-13, apply patches 
13         contained in emails directly, and so on. The only limit is your 
14         imagination. You can configure Actions via the <quote>Tools</quote> 
15         menu.
16     </para>
17     <blockquote>
18       <example>
19         <title>Simple <quote>Open With...</quote></title>
20         <variablelist>
21           <varlistentry>
22             <term>
23         Menu name: <emphasis>Open with/kate</emphasis> 
24         Command Line: <command>kate %p</command>
25             </term>
26             <listitem>
27               <para>
28         Opens the file of the selected decoded MIME part 
29         (<emphasis>%p</emphasis>) with the <emphasis>kate</emphasis> text 
30         editor.
31               </para>
32             </listitem>
33           </varlistentry>
34         </variablelist>
35       </example>
36       <example>
37         <title>Spam management using <ulink 
38           url="http://bogofilter.sourceforge.net/">Bogofilter</ulink>
39         </title>
40         <variablelist>
41           <varlistentry>
42             <term>
43         Menu name: <emphasis>Bogofilter/Mark as Ham</emphasis> 
44         Command Line: <command>bogofilter -n -v -B "%f"</command>
45             </term>
46             <listitem>
47               <para>
48         Marks the currently selected mails (<emphasis>%f</emphasis>) as
49         <quote>not spam</quote> using <emphasis>Bogofilter</emphasis>.
50               </para>
51             </listitem>
52           </varlistentry>
53           <varlistentry>
54             <term>
55         Menu name: <emphasis>Bogofilter/Mark as Spam</emphasis> 
56         Command Line: <command>bogofilter -s -v -B "%f"</command>
57             </term>
58             <listitem>
59               <para>
60         Marks the currently selected mails (<emphasis>%f</emphasis>) as 
61         <quote>spam</quote> using <emphasis>Bogofilter</emphasis>.
62               </para>
63             </listitem>
64           </varlistentry>
65         </variablelist>
66       </example>
67       <example>
68         <title>Search Google using an external script</title>
69         <variablelist>
70           <varlistentry>
71             <term>
72         Menu name: <emphasis>Search/Google</emphasis> 
73         Command Line: <command>|/path/to/google_search.pl</command>
74             </term>
75             <listitem>
76               <para>
77         Searches Google for the currently selected text 
78         (<emphasis>|</emphasis>) using the external script <emphasis><ulink 
79         url="http://www.claws-mail.org/tools.php"
80         >google_search.pl</ulink></emphasis>.
81               </para>
82             </listitem>
83           </varlistentry>
84         </variablelist>
85       </example>
86     </blockquote>
87   </section>
88   <section id="adv_templates">
89     <title>Templates</title>
90     <para>
91         Templates are used in composition windows, and act as a model for 
92         emails. Templates can be filled with static text and dynamic parts, 
93         such as the original sender's name (<quote>Dear %N, ...</quote>), 
94         the date, etc. When applying a template, the dynamic fields will be 
95         replaced with the relevant values. You can configure templates via 
96         the <quote>Tools</quote> menu.
97     </para><para>
98         When applying a template, you will be asked to <quote>Insert</quote>
99         or <quote>Replace</quote>, the difference between replacing and 
100         inserting is only concerned with the message body. 
101         <quote>Replace</quote> will replace the current composition window 
102         message body with the body defined in the template, clearing it if 
103         the template body is empty. <quote>Insert</quote> will insert 
104         the template's body, if set, at the current cursor position.
105     </para><para>
106         Whether you choose to Insert or Replace, any To, Cc or Bcc field 
107         that is defined in the template will be appended to the compose 
108         window's recipients list. If it is defined, the template's Subject 
109         will always replace the compose window's Subject.
110     </para><para>
111         Symbols can be used in all parts of the templates and will be 
112         substituted with their respective dynamic value if possible, otherwise 
113         no value will be used. This often makes more sense if you apply a 
114         template when replying or forwarding, otherwise most of the symbols 
115         value will be undefined. There is no restriction on which symbols can 
116         be used in template parts, even if inserting the body (%M or %Q) may 
117         make no sense in common situations.
118     </para><para>
119         When applying a template, the body is processed first, then the To, Cc,
120         Bcc and Subject fields follow.
121     </para><para>
122         Further information and examples of usage can be found in the 
123         user-contributed FAQ on the Claws Mail website <ulink 
124         url="http://www.claws-mail.org/faq/"
125         >http://www.claws-mail.org/faq/</ulink>.
126     </para>
127    </section>
128   <section id="adv_processing">
129     <title>Processing</title>
130     <para>
131         Processing rules are the same as Filtering rules, except that they are 
132         applied when entering a folder and apply only to this folder. You can 
133         use them to automatically move old mails into an archive folder, or for
134         further dispatching of emails, and more. You can set each folder's 
135         Processing rules by right-clicking on it.
136     </para><para>
137         Processing rules are accompanied by Pre-processing and Post-processing 
138         rules. Like Processing rules, they apply only when opening a folder, 
139         but like Filtering rules, they are shared accross all folders. You can 
140         configure them from the <quote>Tools</quote> menu. Pre-processing rules
141         are executed before the folder's specific Processing rules, while 
142         Post-processing rules are executed afterwards.
143     </para>
144   </section>
145   <section id="adv_colour_labels">
146     <title>Colour Labels</title>
147     <para>
148         Colour labels can be used to denote a message as having a particular 
149         significance. To set a colour label simply right-click a message in the
150         Message List and use the <quote>Color label</quote> submenu.
151     </para><para>
152         Colour labels are user-configurable. Both the colour and the label can 
153         be set by the user. Preferences can be found on the 
154         <quote>Configuration/Preferences/Display/Colors</quote> page.
155     </para>
156   </section>
157   <section id="adv_ml_support">
158     <title>Mailing-List support</title>
159     <para>
160         Claws Mail offers mailing-list support from the 
161         <quote>Message/Mailing-List/</quote> submenu. When you have a 
162         mailing-list message selected, the submenu allows you to quickly 
163         initiate subscribing, unsubscribing, posting, getting help, contacting 
164         the list owner, and viewing the list archive; either by opening a new 
165         Compose window with the appropriate address pre-filled, or by opening 
166         the URL in your web browser.
167     </para>
168   </section>
169   <section id="adv_plugins">
170     <title>Plugins</title>
171     <para>
172         Plugins are the mechanism for extending Claws Mail' capabilities. 
173         For example, imagine that you want to store your mails in a remote 
174         <acronym>SQL</acronym> database. In most mailers out there this is 
175         simply impossible without reworking the internals of the mailer. With 
176         Claws Mail you can simply write a plugin to achieve the task.
177     </para><para>
178         This is just an example of the possibilities. A good number of plugins 
179         developed for Claws Mail already exist, and more are to come. The 
180         <link linkend="ch_plugins">Extending Claws Mail section</link> 
181         gives details of them.
182     </para>
183   </section>
184   <section id="deploying">
185     <title>Deploying Claws Mail</title>
186     <para>
187         The initial configuration wizard tries to guess various fields using 
188         information gathered from the system, such as username, hostname, and 
189         more. As it is oriented towards general use, the default values often 
190         have to be fixed. However, this wizard is customisable, in a manner 
191         designed to allow system administrators to deploy Claws Mail easily
192         over various users of one machine, or even over multiple machines 
193         installed via some replication tool.
194     </para><para>
195         The first part consists of creating a wizard configuration template 
196         and setting the various default parameters of a new Claws Mail 
197         installation.
198     </para>
199     <itemizedlist>
200       <listitem>
201         <para>
202         Start with a user who does not have a <filename class="directory"
203         >~/.claws-mail</filename> directory, ideally a new user.
204         </para>
205       </listitem>
206       <listitem>
207         <para>
208         Start Claws Mail and go through the wizard. The values you fill in 
209         will be of no use for the future deployment, so you can click 
210         next-next-next.
211         </para>
212       </listitem>
213       <listitem>
214         <para>
215         Once the wizard is finished and you have Claws Mail' main window 
216         opened, configure the various defaults you want to have in the master. 
217         You can load plugins, add people or LDAP servers in the addressbook, 
218         create filtering rules, and so on.
219         </para>
220       </listitem>
221       <listitem>
222         <para>
223         If needed, and if the deployed Claws Mail will use MH folders, you 
224         can create subdirectories in the mailbox.
225         </para>
226       </listitem>
227       <listitem>
228         <para>
229         Next, quit Claws Mail.
230         </para>
231       </listitem>
232       <listitem>
233         <para>
234         Now, edit the newly created wizard template file, 
235         <filename>~/.claws-mail/accountrc.tmpl</filename>. In this file, 
236         you will see different variables, corresponding to the wizard's fields.
237         You can leave some commented, in which case the usual default will be 
238         used, or specify values or variables. Not all fields can contain 
239         variables; for example, <literal>smtpauth</literal>, 
240         <literal>smtpssl</literal> and <literal>recvssl</literal> are booleans,
241         either 0 or 1, and <literal>recvtype</literal> is an integer value. The
242         other fields, like <literal>name</literal>, <literal>email</literal>, 
243         or <literal>recvuser</literal>, are parsed by the wizard and the 
244         variables they contain are replaced by values. This allows you to 
245         specify everything as needed for your site, even if you have strange 
246         server names or server logins.
247         </para>
248       </listitem>
249       <listitem>
250         <para>
251         Save this file, and delete both 
252         <filename>~/.claws-mail/accountrc</filename>, (which contains your 
253         dummy account) and 
254         <filename>~/.claws-mail/folderlist.xml</filename>, (so that the 
255         folder tree will be correctly parsed for new users). Recursively copy 
256         <filename class="directory">.claws-mail</filename> to 
257         <filename class="directory">/etc/skel/</filename>; if the deployed 
258         Claws Mail will use MH folders, also copy the created 
259         <filename class="directory">Mail</filename> directory. chown all of 
260         <filename class="directory">/etc/skel/.claws-mail</filename> 
261         and <filename class="directory">/etc/skel/Mail</filename> to 
262         <literal>root:root</literal> for security reasons.
263         </para>
264       </listitem>
265       <listitem>
266         <para>
267         Test! Create a new user, login as that user, run Claws Mail. If you
268         filled everything as you wanted, this user will just have to fill in 
269         his passwords.
270         </para>
271       </listitem>
272       <listitem>
273         <para>
274         Now, if you're creating a master for a site-wide deployment, you can 
275         continue with this process. If you were just doing it for one machine, 
276         you're done!
277         </para>
278       </listitem>
279     </itemizedlist>
280     <para>
281     Here are the different variables of the <filename>accountrc.tmpl</filename>
282     file:
283     </para>
284     <variablelist>
285       <varlistentry>
286         <term><literal>domain</literal></term>
287         <listitem>
288           <para>
289         Your domain name (example.com). If not set, it'll be extracted from the
290         hostname.
291           </para>
292         </listitem>
293       </varlistentry>
294       <varlistentry>
295         <term><literal>name</literal></term>
296         <listitem>
297           <para>
298         The user's name. If not set, it'll be extracted from Unix login 
299         information, which is usually ok.
300           </para>
301         </listitem>
302       </varlistentry>
303       <varlistentry>
304         <term><literal>email</literal></term>
305         <listitem>
306           <para>
307         The user's email. If not set, it'll be extracted from 
308         <literal>$name</literal> and <literal>$domain</literal>.
309           </para>
310         </listitem>
311       </varlistentry>
312       <varlistentry>
313         <term><literal>organization</literal></term>
314         <listitem>
315           <para>
316         Your organization. If not set, it'll be empty.
317           </para>
318         </listitem>
319       </varlistentry>
320       <varlistentry>
321         <term><literal>smtpserver</literal></term>
322         <listitem>
323           <para>
324         The SMTP server to use. If not set, it'll be 
325         <literal>smtp.$domain</literal>.
326           </para>
327         </listitem>
328       </varlistentry>
329       <varlistentry>
330         <term><literal>smtpauth</literal></term>
331         <listitem>
332           <para>
333         0 or 1. Whether to authenticate on the SMTP server. If not set, it'll 
334         be 0.
335           </para>
336         </listitem>
337       </varlistentry>
338       <varlistentry>
339         <term><literal>smtpuser</literal></term>
340         <listitem>
341           <para>
342         The login on the SMTP server. If not set, it'll be empty (same login as
343         for reception will be used).
344           </para>
345         </listitem>
346       </varlistentry>
347       <varlistentry>
348         <term><literal>smtppass</literal></term>
349         <listitem>
350           <para>
351         The password on the SMTP server. If not set, it'll be empty (if 
352         <literal>smtppass</literal> is empty but <literal>smtpuser</literal> is
353         not, the user will be asked for the password).
354           </para>
355         </listitem>
356       </varlistentry>
357       <varlistentry>
358         <term><literal>recvtype</literal></term>
359         <listitem>
360           <para>
361         The type of server to receive from. 0 for POP3, 3 for IMAP4, 5 for a 
362         local MBOX file. If not set, it'll be 0 (POP3).
363           </para>
364         </listitem>
365       </varlistentry>
366       <varlistentry>
367         <term><literal>recvserver</literal></term>
368         <listitem>
369           <para>
370         The reception server. If not set, it'll be 
371         <literal>(pop|imap).$domain</literal>, depending on 
372         <literal>$recvtype</literal>.
373           </para>
374         </listitem>
375       </varlistentry>
376       <varlistentry>
377         <term><literal>recvuser</literal></term>
378         <listitem>
379           <para>
380         The login on the reception server. If not set, it'll be extracted from 
381         the Unix login information.
382           </para>
383         </listitem>
384       </varlistentry>
385       <varlistentry>
386         <term><literal>recvpass</literal></term>
387         <listitem>
388           <para>
389         The password on the reception server. If not set, it'll be empty (the 
390         user will be asked for it once per session).
391           </para>
392         </listitem>
393       </varlistentry>
394       <varlistentry>
395         <term><literal>imapdir</literal></term>
396         <listitem>
397           <para>
398         The IMAP subdirectory. If not set, it'll be empty, which is often 
399         sufficient.
400           </para>
401         </listitem>
402       </varlistentry>
403       <varlistentry>
404         <term><literal>mboxfile</literal></term>
405         <listitem>
406           <para>
407         The MBOX file to receive from if <literal>$recvtype</literal> is 5. 
408         If not set, <literal>/var/mail/$LOGIN</literal>.
409           </para>
410         </listitem>
411       </varlistentry>
412       <varlistentry>
413         <term><literal>mailbox</literal></term>
414         <listitem>
415           <para>
416         The MH mailbox to store mail in (for <literal>$recvtype</literal> 0 or 
417         5). If not set, it'll be <quote>Mail</quote>.
418           </para>
419         </listitem>
420       </varlistentry>
421       <varlistentry>
422         <term><literal>smtpssl</literal></term>
423         <listitem>
424           <para>
425         0 or 1. Whether to use SSL for sending mail. If not set, it'll be 0.
426           </para>
427         </listitem>
428       </varlistentry>
429       <varlistentry>
430         <term><literal>recvssl</literal></term>
431         <listitem>
432           <para>
433         0 or 1. Whether to use SSL for receiving mail. If not set, it'll be 0.
434           </para>
435         </listitem>
436       </varlistentry>
437     </variablelist>
438     <para>
439         Here are the different variables you can use in the 
440         <literal>domain</literal>, <literal>name</literal>, 
441         <literal>email</literal>, <literal>organization</literal>, 
442         <literal>smtpserver</literal>, <literal>smtpuser</literal>, 
443         <literal>smtppass</literal>, <literal>recvserver</literal>, 
444         <literal>recvuser</literal>, <literal>recvpass</literal>, 
445         <literal>imapdir</literal>, <literal>mboxfile</literal> and 
446         <literal>mailbox</literal> fields:
447     </para>
448     <variablelist>
449       <varlistentry>
450         <term><literal>$DEFAULTDOMAIN</literal></term>
451         <listitem>
452           <para>
453         The domain name as extracted from Unix hostname information. 
454         Often wrong.
455           </para>
456         </listitem>
457       </varlistentry>
458       <varlistentry>
459         <term><literal>$DOMAIN</literal></term>
460         <listitem>
461           <para>
462         The domain name as set in the domain variable, the first of the 
463         template file.
464           </para>
465         </listitem>
466       </varlistentry>
467       <varlistentry>
468         <term><literal>$USERNAME</literal></term>
469         <listitem>
470           <para>The user's real name.</para>
471         </listitem>
472       </varlistentry>
473       <varlistentry>
474         <term><literal>$LOGIN</literal></term>
475         <listitem>
476           <para>The user's Unix login.</para>
477         </listitem>
478       </varlistentry>
479       <varlistentry>
480         <term><literal>$NAME_MAIL</literal></term>
481         <listitem>
482           <para>
483         The user's real name as set in the name variable of the template field,
484         in lowercase and with spaces replaced by dots. 
485         <quote>Colin Leroy</quote> becomes <quote>colin.leroy</quote>.
486           </para>
487         </listitem>
488       </varlistentry>
489       <varlistentry>
490         <term><literal>$EMAIL</literal></term>
491         <listitem>
492           <para>
493         The email address as set in the email variable of the template field.
494           </para>
495         </listitem>
496       </varlistentry>
497     </variablelist>
498     <para>
499         Be sure not to use a variable before defining it.
500     </para>
501   </section>
502   <section id="adv_hidden">
503     <title>Hidden preferences</title>
504     <para>
505         There are a number of hidden preferences in Claws Mail, preferences
506         that some users who we wanted to please couldn't live without, but 
507         which did not have a place in the GUI in our opinion. You can find the 
508         following, and change them while Claws Mail is not running, in 
509         <filename>~/.claws-mail/clawsrc</filename>.
510     </para>
511     <variablelist>
512       <varlistentry>
513         <term><literal>addressbook_use_editaddress_dialog</literal></term>
514         <listitem>
515           <para>
516         Use a dialog to edit person details. '0': use an form embedded in
517         the addressbook's main window. '1' (default): use a separate dialog.
518           </para>
519         </listitem>
520       </varlistentry>
521       <varlistentry>
522         <term><literal>bold_unread</literal></term>
523         <listitem>
524           <para>
525         Show unread messages in the Message List using a bold font.
526           </para>
527         </listitem>
528       </varlistentry>
529       <varlistentry>
530         <term><literal>cache_max_mem_usage</literal></term>
531         <listitem>
532           <para>
533         The maximum amount of memory to use to cache messages, in kB.
534           </para>
535         </listitem>
536       </varlistentry>
537       <varlistentry>
538         <term><literal>cache_min_keep_time</literal></term>
539         <listitem>
540           <para>
541         The minimum time in minutes to keep a cache in memory. Caches more 
542         recent than this time will not be freed, even if the memory usage is 
543         too high.
544           </para>
545         </listitem>
546       </varlistentry>
547       <varlistentry>
548         <term><literal>compose_no_markup</literal></term>
549         <listitem>
550           <para>
551         Don't use bold and italic text in Compose dialogue's account selector.
552           </para>
553         </listitem>
554       </varlistentry>
555       <varlistentry>
556         <term><literal>enable_dotted_lines</literal></term>
557         <listitem>
558           <para>
559         Use the <emphasis>old</emphasis> dotted line look in the main window
560         GtkTreeView components, (Folder List and Message List), instead of the
561         <emphasis>modern</emphasis> lineless look.
562           </para>
563         </listitem>
564       </varlistentry>
565       <varlistentry>
566         <term><literal>enable_hscrollbar</literal></term>
567         <listitem>
568           <para>
569         Enable the horizontal scrollbar in the Message List.
570           </para>
571         </listitem>
572       </varlistentry>
573       <varlistentry>
574         <term><literal>enable_swap_from</literal></term>
575         <listitem>
576           <para>
577         Display the sender's email address in the To column of the
578         Sent folder instead of the recipient's.
579           </para>
580         </listitem>
581       </varlistentry>
582       <varlistentry>
583         <term><literal>folderview_vscrollbar_policy</literal></term>
584         <listitem>
585           <para>
586         Specify the policy of vertical scrollbar of Folder List.
587         '0' is always shown, '1' is automatic, '2' is always hidden.
588           </para>
589         </listitem>
590       </varlistentry>
591       <varlistentry>
592         <term><literal>hover_timeout</literal></term>
593         <listitem>
594           <para>
595         Time in milliseconds that will cause a folder tree to expand 
596         when the mouse cursor is held over it during drag 'n' drop.
597           </para>
598         </listitem>
599       </varlistentry>
600       <varlistentry>
601         <term><literal>live_dangerously</literal></term>
602         <listitem>
603           <para>
604         Don't ask for confirmation before definitive deletion of emails.
605           </para>
606         </listitem>
607       </varlistentry>
608       <varlistentry>
609         <term><literal>log_error_color</literal></term>
610         <term><literal>log_in_color</literal></term>
611         <term><literal>log_msg_color</literal></term>
612         <term><literal>log_out_color</literal></term>
613         <term><literal>log_warn_color</literal></term>
614         <listitem>
615           <para>
616         The colours used in the log window.
617           </para>
618         </listitem>
619       </varlistentry>
620       <varlistentry>
621         <term><literal>respect_flowed_format</literal></term>
622         <listitem>
623           <para>
624         0 or 1. Respect format=flowed on text/plain message parts. This
625         will cause some mails to have long lines, but will fix some URLs
626         that would otherwise be wrapped. Default is 0, turned off.
627           </para>
628         </listitem>
629       </varlistentry>
630       <varlistentry>
631         <term><literal>skip_ssl_cert_check</literal></term>
632         <listitem>
633           <para>
634         Disables the verification of SSL certificates.
635           </para>
636         </listitem>
637       </varlistentry>
638       <varlistentry>
639         <term><literal>statusbar_update_step</literal></term>
640         <listitem>
641           <para>
642         Update stepping in progress bars.
643           </para>
644         </listitem>
645       </varlistentry>
646       <varlistentry>
647         <term><literal>stripes_color_offset</literal></term>
648         <listitem>
649         <para>
650         Specify the value to use when creating alternately coloured lines in
651         GtkTreeView components. The smaller the value, the less visible the
652         difference in the alternating colours of the lines.
653         </para>
654         </listitem>
655       </varlistentry>
656       <varlistentry>
657         <term><literal>textview_cursor_visible</literal></term>
658         <listitem>
659           <para>
660         Display the cursor in the message view.
661           </para>
662         </listitem>
663       </varlistentry>
664       <varlistentry>
665         <term><literal>thread_by_subject_max_age</literal></term>
666         <listitem>
667           <para>
668         Number of days to include a message in a thread when using 
669         <quote>Thread using subject in addition to standard headers</quote>.
670           </para>
671         </listitem>
672       </varlistentry>
673       <varlistentry>
674         <term><literal>toolbar_detachable</literal></term>
675         <listitem>
676           <para>
677         Show handles in the toolbars.
678           </para>
679         </listitem>
680       </varlistentry>
681       <varlistentry>
682         <term><literal>unsafe_ssl_certs</literal></term>
683         <listitem>
684         <para>
685         Allows Claws to remember multiple SSL certificates for a given 
686         server/port. This is disabled by default.
687         </para>
688         </listitem>
689       </varlistentry>
690       <varlistentry>
691         <term><literal>use_stripes_everywhere</literal></term>
692         <listitem>
693         <para>
694         Enable alternately coloured lines in GtkTreeView components.
695         </para>
696         </listitem>
697       </varlistentry>
698       <varlistentry>
699         <term><literal>use_stripes_in_summaries</literal></term>
700         <listitem>
701         <para>
702         Enable alternately coloured lines in the main window GtkTreeView
703         components, (Folder List and Message List). The only useful way to
704         use this option is to set it to 0 when use_stripes_everywhere is set
705         to 1.
706         </para>
707         </listitem>
708       </varlistentry>
709       <varlistentry>
710         <term><literal>utf8_instead_of_locale_for_broken_mail</literal></term>
711         <listitem>
712           <para>
713         Use UTF-8 encoding for broken mails instead of current locale.
714           </para>
715         </listitem>
716       </varlistentry>
717       <varlistentry>
718         <term><literal>warn_dnd</literal></term>
719         <listitem>
720           <para>
721         Display a confirmation dialogue on drag 'n' drop of folders.
722           </para>
723         </listitem>
724       </varlistentry>
725     </variablelist>
726   </section>
727 </section>
728