2007-08-20 [colin] 2.10.0cvs137
[claws.git] / tools / README
1
2 --------------------------------------------------------------------------------
3 Contents of the tools directory:
4 --------------------------------------------------------------------------------
5
6 Action scripts:
7   freshmeat_search.pl           Search freshmeat.net for selected text
8   google_msgid.pl               Search groups.google.com for selected message-id
9   google_search.pl              Search google.com for selected text
10   multiwebsearch.pl             Search any search engine for the selected text
11   textviewer.sh                 Attempt to view an attachment as plain text
12   uudec                         Decode and display uuencoded images
13   uuooffice                     Decode uuencoded attachments and open them with
14                                 OpenOffice
15
16 Addressbook conversion:
17   eud2gc.py                     Convert Eudora address book to Gnomecard
18   kmail2claws-mail.pl           Import a Kmail address book (KDE2)
19   kmail2claws-mail_v2.pl        Import a Kmail address book (KDE3)
20   outlook2claws-mail.pl         Import an Outlook generated contact list
21   tb2claws-mail                 Import The Bat! address books
22   vcard2xml.py                  Import an Evolution vCard
23
24 Mailbox conversion:
25   calypso_convert.pl            Import mbox files with attachments from Calypso
26   convert_mbox.pl               Import mbox files
27   kmail-mailbox2claws-mail.pl   Convert a kmail mailbox to a Claws Mail mailbox
28   tbird2claws.py                Integrate a Thunderbird folder tree into Claws
29
30 Other tools:
31   acroread2claws-mail.pl        Send PDFs from Adobe Reader 7
32   claws-mail-compose-insert-files.pl
33                                 Insert files into a new Compose window
34   filter_conv_new.pl            Convert new-style Sylpheed filters to filtering
35   filter_conv.pl                Convert old-style Sylpheed filters to filtering
36   fix-date.sh                   Replace/Add a message's Date field
37   mairix.sh                     A wrapper to mairix, to enable global searches in
38                                 mail folders
39   nautilus2claws-mail.sh        Send files from Nautilus
40   OOo2claws-mail.pl             Send documents from OpenOffice.org
41   popfile-link.sh               Open messages in POPFile control center to edit
42                                 their status
43   sylprint.pl                   Printing engine, explained in README.sylprint
44   textviewer.pl                 Display various attachments as text
45   thunderbird-filters-convertor.pl
46                                 Convert Thunderbird filtering rules
47
48 Extra tools:
49   gif2xface.pl                  Convert a 48x48 GIF file to an X-Face header
50   update-po                     Update the .po files named on the command line.
51
52 --------------------------------------------------------------------------------
53 Detailed Descriptions:
54 --------------------------------------------------------------------------------
55
56 Action scripts
57 --------------
58
59 * freshmeat_search.pl
60   WORKS ON: selection
61   COMMAND: |freshmeat_search.pl
62   Search freshmeat.net for selected text using the default Claws Mail browser
63
64 * google_msgid.pl
65   WORKS ON: selection
66   COMMAND: |google_msgid.pl
67   Lookup selected message-id in google using mozilla. Edit the script to use
68   different browsers.
69
70 * google_search.pl
71   WORKS ON: selection
72   COMMAND: |google_search.pl
73   Search google.com for selected text using the default Claws Mail browser
74
75 * multiwebsearch.pl
76   WORKS ON: selection
77   see further down for details
78
79 * textviewer.sh
80   WORKS ON: current message part
81   COMMAND: textviewer.sh %p |
82   Attempt to view an attachment as plain text
83
84 * uudec
85   WORKS ON: current message (or part of multipart message)
86   COMMAND: uudec %f&
87   Decode and display uuencoded images using uudecode.
88
89 * uuooffice
90   WORKS ON: current message (or part of multipart message)
91   COMMAND: uuooffice %f&
92   Decode uuencoded attachments and open them with OpenOffice
93
94 * More action examples can be found at the Claws Mail FAQ
95   http://www.claws-mail.org/faq/index.php/Actions
96
97 ** multiwebsearch.pl **
98
99   WHAT IT DOES
100         This is an Actions script that allows you to search
101         websites for the selected text. It uses the default
102         Claws Mail browser as configured through Claws Mail's 
103         GUI and specified in ~/.claws-mail/clawsrc, and a
104         configuration file called multiwebsearch.conf.
105         
106   CONFIGURATION
107         The configuration file takes the following format:
108         
109         ALIAS|URL PART|URL PART
110         
111         ALIAS is a user-defined name; the first URL PART is the
112         url before the search term; the second URL PART is
113         optional and contains the remaining part of the url which
114         comes after the search term. A sample configuration file
115         is included.
116         
117   HOW TO USE IT
118         Copy 'multiwebsearch.conf' to ~/.claws-mail/
119         
120         Configure an Action:
121         a) pre-configured website 
122            Command: multiwebsearch.pl --where="google" --what="%s"
123         b) dynamic
124            Command: multiwebsearch.pl --where="%u" --what="%s"
125            
126         In type a) "google" refers to one of the configured aliases,
127         this Action will always search the website referred to by
128         the alias "google".
129         
130         In type b) you will be presented with a dialog box into
131         which you type one of your configured aliases
132
133   
134   Contact: Paul Mangan <paul@claws-mail.org>
135 --------------------------------------------------------------------------------
136
137 Address book conversion
138 -----------------------
139
140 * eud2gc.py
141
142   WHAT IT DOES
143         This python-script is a quick hack to convert an Eudora (v.3?)
144         addressbook to vCard (GnomeCard) format.
145
146   HOW TO USE IT
147         You may do whatever you want with it! (Also regarding copying)
148         However, the script is intended to use like this:
149
150                 eud2gc.py <Eudora-addressbook-file> <Gnomecard-file>
151
152         Be careful not to overwrite your original GnomeCard.gcrd!
153         (But of course you might want to add the converted stuff to it)
154
155   Contact: Jeroen Versteeg <j.m.versteeg@student.utwente.nl>
156
157 * kmail2claws-mail.pl
158
159   WHAT IT DOES
160         This perl script will convert an exported Kmail addressbook into a
161         Claws Mail addressbook. If your version of Kmail is 1.37 or
162         greater and/or your version of KAddressBook is 3.1beta1 or greater,
163         or this script mixes up your definitions and their related data, use
164         'kmail2claws-mail_v2.pl' instead.
165
166   HOW TO USE IT
167         (You must run claws-mail at least once before running this script.)
168
169         In Kmail's Address book choose '/File/Export List'. This will export
170         your Kmail address book data to a *.csv file.
171
172         If Claws Mail is running, close it.
173
174         From the command line, execute the following:
175  
176                 perl kmail2claws-mail.pl --kmailfile=/path/to/addressbook.csv
177
178         Your Kmail address book data will now be contained in Claws Mail'
179         address book, under the name 'Kmail Address Book'.
180
181   Contact: Paul Mangan <paul@claws-mail.org>
182     
183
184 * kmail2claws-mail_v2.pl
185
186   This script has been tested with Kmail 1.4.7 and KAddressBook 3.1beta1
187
188   WHAT IT DOES
189         This perl script will convert a Kmail address book that has been
190         exported in csv format into a Claws Mail address book.
191
192   HOW TO USE IT
193         (You must run claws-mail at least once before running this script.)
194   
195         Open Kmail's Addressbook, /File/Address Book
196         In Kmail's Addressbook choose '/File/Export/Export List...'. This 
197         will allow you to export your Kmail addressbook data to a *.csv file.
198
199         If Claws Mail is running, close it.
200
201         From the command line, execute the following:
202  
203                 perl kmail2claws-mail_v2.pl --kmailfile=/path/to/addressbook.csv
204         
205         You can also use --help to see usage instructions.
206
207         Your Kmail addressbook data will now be contained in Claws Mail'
208         addressbook, under the name 'Kmail address book'.
209
210   Contact: Paul Mangan <paul@claws-mail.org>
211
212
213 * outlook2claws-mail.pl
214
215   WHAT IT DOES
216         This perl script converts an Outlook generated contact list into a 
217         Claws Mail XML address book.
218
219   HOW TO USE IT
220         For text files:
221         --------------
222         You must export Outlook Express contact list as TXT file, choosing
223         only "Name" and "Address" fields to export.
224
225         You must exit Claws Mail before converting the contact list.
226
227         From the command line, execute the following:
228
229                 outlook2claws-mail.pl fullpathname
230
231         For csv files:
232         -------------
233         You must export Outlook contact list as CSV file, choosing ALL the
234         fields available for exporting.
235
236         You must exit Claws Mail before converting the contact list.
237
238         From the command line, execute the following:
239
240                 outlook2claws-mail.pl --csv fullpathname
241
242   LIMITATIONS
243         For text files only works with fields described above. If you have 
244         more complex examples send them to me, and I'll try to enhance the 
245         script.
246
247         For csv files you must export all fields (but only non empty fields
248         are added to the created Claws Mail address book) and the number
249         of fields expected is harcoded. Look for the $nboffields variable in
250         the script and change its value if you are sure you exported all
251         fields and script gives the 'unknown csv file format' error.
252
253   Contact: Ricardo Mones Lastra <mones@aic.uniovi.es>
254
255
256 * tb2claws-mail
257
258   WHAT IT DOES
259         This perl script will convert an address book exported from The Bat! 
260         into a Claws Mail address book.
261
262   HOW TO USE IT
263         (You must run claws-mail at least once before running this script.)
264
265         If Claws Mail is running, close it.
266
267         Export The Bat! Address Book to CSV file format with all fields 
268         selected to YES and then start:
269
270                 tb2claws-mail --tbfile=/full/path/to/thebat/addressbook.csv
271  
272         The Bat! addressbook data will now be contained in Claws Mail'
273         addressbook, under the name 'The Bat! Address Book'.
274
275   Contact: Urke MMI <urke@gmx.net>  
276
277
278 * vcard2xml.py
279
280   WHAT IT DOES
281         This python script will convert an Evolution vCard into a Claws Mail
282         address book.
283
284   HOW TO USE IT
285         (You must run claws-mail at least once before running this script.)
286
287         If Claws Mail is running, close it.
288         From the command line, execute the following:
289
290                 vcard2xml.py source_file [destination_file]
291  
292         When only <source_file> is specified it will overwrite (and
293         create a backup of) the existing addressbook. 
294         When both arguments are suplied it will create a new additional 
295         addressbook named as <destination_file>.
296         If the script encounters an error it will attempt to roll back
297         the changes and restore the original files.
298
299   Contact: Bogdan Sumanariu <bsumanariu@one5.ro> 
300
301 --------------------------------------------------------------------------------
302
303 Mailbox conversion
304 ------------------
305
306 * calypso_convert.pl
307
308   WHAT IT DOES
309         This perl script imports mbox files that are exported by Calypso.
310         It recreates the folder structure by scanning the "X-CalypsoFolder"
311         header and reincludes the attachments referenced in the
312         "X-CalypsoHtmlBody" "X-CalypsoAccount" "X-Attachment" headers.
313   
314   HOW TO USE IT
315         Export the Calypso mailbox by selecting "Save to archive" and check
316         the "Save attachments" box.
317         
318         Edit the script to set following variables (at the top of the file):
319            $mboxdir  : path to the exported mbox, e.g. 'Archive' or '.'
320            $mboxfile : name of exported mbox, e.g. 'mail.txt'
321            $outdir   : name of the MH folder to create, e.g. 'Calypso'
322            
323          Run the script using
324          
325                 perl calypso_convert.pl
326                 
327         Finally, import that folder by either selecting "New mailbox" or
328         moving it into your existing directory and recreate the folder
329         structure manually (contentmenu from folderview).
330
331   Contact: Thorsten Maerz <torte@netztorte.de>
332
333 * convert_mbox.pl
334
335   WHAT IT DOES
336         This perl script converts an mbox directory's contents into 
337         Claws Mail' MH format.
338   
339   HOW TO USE IT
340   
341         Run the script using:
342          
343                 perl convert_mbox.pl MBOX MH_DIR
344                 
345         Move the outputted MH_DIR and its contents into your Claws Mail
346         Mail folder; in Claws Mail right-click the top-level folder and
347         choose 'Rebuild folder tree' from the popup menu.
348
349   Contact: Fred Marton <Fred.Marton@uni-bayreuth.de>
350
351 * kmail-mailbox2claws-mail.pl
352
353   WHAT IT DOES
354         This perl script converts a kmail mailbox  into Claws Mail' mailbox.
355   
356   HOW TO USE IT
357   
358         Exit Claws Mail if running.
359         
360         Run the script using:
361          
362                 kmail-mailbox2claws-mail.pl --kmaildir=/full/path/to/kmail/mailbox
363                 
364         Start Claws Mail and right-click the toplevel mailbox, i.e
365         "Mailbox (MH)", and select 'Rebuild folder tree'.
366         You may also need to run '/File/Folder/Check for new messages
367         in all folders'
368         
369         Additional options:
370                 --debug         debug mode
371                 --dry-run       test mode, nothing is actually written
372                 --help          brief usage info
373         
374   Contact: Paul Mangan <paul@claws-mail.org>
375
376 * tbird2claws.py
377
378   WHAT IT DOES
379         This python script integrates a Thunderbird folder tree into 
380         Claws Mail.
381   
382   HOW TO USE IT
383   
384         The script receives two parameters from command-line:
385         <Thunderbird folder path> <Claws Mail folder path>
386
387         The best way to use it is to go to inside your Thunderbird
388         root mailfolder directory and invoke it as:
389
390                 <path>\python2.4 <path>\tbird2claws.py . <path to Claws Mail>\Mail
391
392   Contact: Aleksandar Urosevic aka Urke MMI <urke@gmx.net>
393
394 --------------------------------------------------------------------------------
395
396 Other tools
397 -----------
398
399 * acroread2claws-mail.pl
400
401   WHAT IT DOES
402         This perl script enables Adobe Reader 7 to send documents to
403         Claws Mail as attachments.
404
405   HOW TO USE IT
406         Make sure that the script is executable (chmod +x acroread2claws-mail.pl)
407         Start up Adobe Reader 7 (acroread)
408         Go to /Edit/Preferences/SendMail
409         Select any email client except 'System Mail (mail)'
410         Enter the path to this script in the alternate location box  
411
412         You can then use 'File/Email' or the Email toolbar button to launch
413         claws-mail (if not already launched) and open a new compose window
414         with the PDF attached.
415   
416   Contact: Paul Mangan <paul@claws-mail.org>
417
418 * claws-mail-compose-insert-files.pl
419
420   WHAT IT DOES
421         This script enables inserting files into the message body of a new 
422         Claws Mail Compose window from the command line. Additionally To,
423         Cc, Subject and files to attach to the message can be specified. 
424
425   HOW TO USE IT
426         claws-mail-compose-insert-files.pl [options]
427         Options:
428                 --help -h
429                 --to mail@address.net[,mail2@address.net]
430                 --cc mail@address.net[,mail2@address.net]
431                 --subject "My subject"
432                 --attach FILE
433                 --insert FILE
434
435         --attach and --insert can be used multiple times
436   
437   Contact: Paul Mangan <paul@claws-mail.org>
438
439 * filter_conv_new.pl
440
441   WHAT IT DOES
442         This perl script provides easy conversion of your filtering rules from
443         sylpheed's new filter system (>= 0.9.99) to the filtering system used in
444         Claws Mail.
445         It reads '~/.sylpheed-2.0/filter.xml' or '~/.sylpheed/filter.xml' and
446         writes '~/[CLAWS CONFIG DIR]/matcherrc'
447   
448   HOW TO USE IT
449         Issue the following command from the 'tools' directory:
450
451         perl filter_conv_new.pl
452
453         That's it, the claws' filtering system is now implemented with your
454         previous rules applied.
455
456   REQUIREMENTS
457         XML::SimpleObject
458
459   Contact: Paul Mangan <paul@claws-mail.org>
460   
461
462 * filter_conv.pl
463
464   WHAT IT DOES
465         This perl script provides easy conversion of your filtering rules
466         from sylpheed's old filter system (< 0.9.99) to the filtering system
467         used in Claws Mail.
468         It reads '~/.sylpheed/filterrc' and writes '~/.claws-mail/matcherrc'
469   
470   HOW TO USE IT
471         Issue the following command from the 'tools' directory:
472
473         perl filter_conv.pl
474
475         That's it, the new filtering system is now implemented with your
476         previous rules applied.
477
478   Contact: Paul Mangan <paul@claws-mail.org>
479   
480
481 * fix-date.sh
482
483  WHAT IT DOES
484         It will replace the Date: value w/ the one picked up from
485         more recent Received: field if this field resides in one
486         line. Otherwise, it will take the file modification time
487         (using a RFC 2822-compliant form). If no X-Original-Date already
488         exist, the former Date value will be set in such field.
489
490   HOW TO USE IT
491         fix_date.sh <filename> [<filename>..]
492
493   Contact: wwp <wwp@claws-mail.org>
494
495
496 * mairix.sh
497
498  WHAT IT DOES
499         It's a wrapper to mairix, a tool that makes indexed searches
500         and shows search results in a virtual folder. Maildir, MH and
501         mbox formats are supported, see:
502         http://www.rpcurnow.force9.co.uk/mairix/
503
504   HOW TO USE IT
505         mairix.sh
506         mairix.sh <mairix rcfile> [<mairix options>..]
507     
508     For instance:    
509     mairix.sh ~/.mairixrc s:word1,word2
510
511   Contact: wwp <wwp@claws-mail.org>
512
513
514 * nautilus2claws-mail.sh
515
516   WHAT IT DOES
517         This script will recursively attach a number of selected 
518         files/directories from Nautilus to a new blank e-mail.
519
520   HOW TO USE IT
521         Copy the script to $HOME/.gnome2/nautilus-scripts, chmod u+x, 
522         and restart nautilus (killall -9 nautilus). You will now have 
523         a right-click menu item: '/Scripts/nautilus2claws-mail.sh'
524         
525   Contact: Reza Pakdel <hrpakdel@cpsc.ucalgary.ca>
526
527
528 * OOo2claws-mail.pl
529
530   WHAT IT DOES
531         This perl script enables OpenOffice.org to send documents to
532         Claws Mail as attachments.
533
534   HOW TO USE IT
535     OpenOffice.org Version 2.0
536     ----------------------------
537         This script is not needed for OOo version 2, which can work
538         directly with Claws Mail.
539         Go to 'Tools/Options/Internet/E-mail' and enter 'claws-mail'
540         in the box.
541
542     OpenOffice.org Version 1.1.0
543     ----------------------------
544         Start up OpenOffice.org.
545         Go to 'Tools/Options/OpenOffice.org/External Programs'
546         Select either ''Mozilla 1.x (Option 1)', or 
547         'Netscape 6.x - 7.0 (Option 1)' from the 'Program' selection
548         Enter the path to OOo2claws-mail.pl in the 'Path' box
549         or select it by clicking on the '...' button.
550     
551         You can then use 'File/Send/Document as email' to launch
552         claws-mail (if not already launched) and open a new compose
553         window with the document attached.
554
555     OpenOffice.org Version 1.0
556     --------------------------
557         Start up OpenOffice.org.
558         Go to 'Tools/Options/OpenOffice.org/External Programs'
559         Enter the path to OOo2claws-mail.pl in the 'Program' box
560         or select it by clicking on the '...' button.
561
562
563   Contact: Paul Mangan <paul@claws-mail.org>
564
565
566 * popfile-link.sh
567
568  WHAT IT DOES
569         Open selected messages in POPFile control center to edit their
570         status. Requires that POPFile is running and that the messages
571         have been processed by it (X-POPFile-Link: header is expected).
572         POPFile control center opens with the web browser set in
573         Claws Mail prefs.
574
575   HOW TO USE IT
576         popfile-link.sh <filename> [<filename>..]
577     
578
579   Contact: wwp <wwp@claws-mail.org>
580
581
582 * textviewer.pl
583
584   WHAT IT DOES
585         This script tries to recognise an attachment by using the 'file'
586         command and/or the file extension and then uses the available Linux
587         utilities to make an effort to display it as text. For example
588                 .doc                    antiword -w 72
589                 .txt, .diff, .c, .h,
590                   .ic. .ec, .cc, .sh,
591                   .sed, .awk            cat
592                 .html                   txt2htm or text2html
593                 .xls, .sxc, .csv        xlscat -L
594                 .rtf                    rtf2text
595                 .pdf                    pdf2text %f -
596                 .odt                    ooo2txt
597                 .pl, .pm                perltidy -st -se or  cat
598                 .bz2                    bzip2 -d < %f | strings
599
600   HOW TO USE IT
601         Go to /Configuration/Message View/External Programs and enter the
602         path to the script in the "Command for 'Display as text'" box.
603         Now when you right-click an attachment and choose 'Display as text'
604         this script will be invoked.
605
606         
607   Contact: H.Merijn Brand <h.m.brand@xs4all.nl>
608
609
610 * thunderbird-filters-convertor.pl
611
612   WHAT IT DOES
613         This perl script converts Thunderbird filtering rules into Claws Mail
614         filtering rules. It can be run several times, once for each filter
615         configuration file in Thunderbird.
616
617   HOW TO USE IT
618         The script takes 3 arguments:
619
620         --tbird-file=PATH TO FILE       The full path to the file to be converted
621         --mailbox-name=NAME             The name of the Claws Mail mailbox
622         --account-name=NAME             The name of the account to be used (optional)   
623
624         --tbird-file must point to the Thunderbird filter file (msgFilterRules.dat)
625         that you want to convert, it must contain the full path to the file.
626         --mailbox-name should be given the name of your mailbox in Claws Mail, e.g.
627         if the top-level folder is 'Mailbox (MH)' then this option should be
628         'Mailbox'.
629         --account-name is optional, only needed if you are creating account-specific
630         rules. This is the name of your account in Claws Mail, which should
631         correspond to an account that you had in Thunderbird, e.g. the acount whose
632         rules you are converting.
633
634         This script presumes that your folder hierarchy in Claws Mail matches the
635         one that you had in Thunderbird. If you used the tbird2claws.py script to
636         convert your Thunderbird mailbox, then the folder hierarchy should match.
637
638         If the Claws Mail filtering configuration file (matcherrc) does not exist,
639         the script will create it; if it does exist, the newly converted rules will
640         be appended to it.
641
642   REQUIREMENTS
643         Getopt::Long
644         URI::Escape
645
646   Contact: Paul Mangan <paul@claws-mail.org>
647
648 --------------------------------------------------------------------------------
649
650 Extra tools
651 -----------
652
653 * gif2xface.pl
654
655   WHAT IT DOES
656         This perl script converts a monochrome (1 bit) 48x48 pixels GIF file
657         into an X-Face graphic suitable for inclusion into custom headers of
658         Claws Mail. An X-Face allows to quickly identify (or be identified
659         as) the sender of a mail message in a xface-capable MUA (like Claws
660         Mail).
661
662   HOW TO USE IT
663         After obtaining the desired image for your X-Face you should:
664           * scale it to 48x48 pixels (Image->Scale image on Gimp)
665           * down color depth to b/w (Image->Mode->Indexed selecting "Use
666             Black/White palette" and the desired dithering options (prior to
667             indexing doing Image->Colors->Threshold allows you to select the
668             b/w level if you don't want a dithered (dotty) image))
669           * save file as non-interlaced GIF
670         Then do:
671
672                 ./gif2xface < filename.gif > filename.xface
673
674         In filename.xface will be the X-Face header ready to use.
675         You can add a custom header in Claws Mail through Configuration->
676         Preferences per account, "Send" tab, check "Add user-defined header"
677         then "Edit..." if you want to add it via the Claws Mail interface, or do
678
679                 echo "0:" `cat filename.xface` > ~/.claws-mail/customheaderrc
680
681         if you want to create the custom headers file yourself (Warning: this
682         method is valid only if you don't have any other custom header set or
683         they will be lost!).
684
685   Contact: Ricardo Mones Lastra <mones@aic.uniovi.es>
686
687
688 * update-po
689
690   WHAT IT DOES
691         This script is a message catalog translator's tool, it updates the .po 
692         files named on the command line.
693
694   HOW TO USE IT
695         This script needs to be copied to and run from the 'po' directory.
696   
697                 ./update-po lang.po lang2.po ...
698
699         to update one or more <yourlang>.po files from the sourcecode files
700          named in POTFILES.in. The old .po file is save in a .po.old file.
701
702         For example, when you want to update fr.po, run ./update-po fr.po, 
703         then edit fr.po to update your translation.
704
705   Contact: Wilbert Berendsen <wilbert@oswf.org> or the Claws Mail Team
706
707 --------------------------------------------------------------------------------