2006-08-01 [wwp] 2.4.0cvs10
[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
14 Addressbook conversion:
15   eud2gc.py                     Convert Eudora address book to Gnomecard
16   kmail2sylpheed.pl             Import a Kmail address book (KDE2)
17   kmail2sylpheed_v2.pl          Import a Kmail address book (KDE3)
18   outlook2sylpheed.pl           Import an Outlook generated contact list
19   tb2sylpheed                   Import The Bat! address books
20   vcard2xml.py                  Import an Evolution vCard
21
22 Mailbox conversion:
23   calypso_convert.pl            Import mbox files with attachments from Calypso
24   convert_mbox.pl               Import mbox files
25   maildir2sylpheed.pl           Convert a maildir mailbox to MH format
26   tbird2syl.py                  Integrate a Thunderbird folder tree into Claws
27
28 Other tools:
29   acroread2sylpheed.pl          Send PDFs from Adobe Reader 7
30   filter_conv_new.pl            Convert new-style Sylpheed filters to filtering
31   filter_conv.pl                Convert old-style Sylpheed filters to filtering
32   nautilus2sylpheed.sh          Send files from Nautilus
33   OOo2sylpheed.pl               Send documents from OpenOffice.org
34   sylprint.pl                   Printing engine, explained in README.sylprint
35   update-po                     Update the .po files named on the command line.
36
37 Extra tools:
38   gif2xface.pl                  Convert a 48x48 GIF file to an X-Face header
39
40 --------------------------------------------------------------------------------
41 Detailed Descriptions:
42 --------------------------------------------------------------------------------
43
44 Action scripts
45 --------------
46
47 * freshmeat_search.pl
48   WORKS ON: selection
49   COMMAND: |freshmeat_search.pl
50   Search freshmeat.net for selected text using the default Sylpheed-Claws browser
51
52 * google_msgid.pl
53   WORKS ON: selection
54   COMMAND: |google_msgid.pl
55   Lookup selected message-id in google using mozilla. Edit the script to use
56   different browsers.
57
58 * google_search.pl
59   WORKS ON: selection
60   COMMAND: |google_search.pl
61   Search google.com for selected text using the default Sylpheed-Claws browser
62
63 * multiwebsearch.pl
64   WORKS ON: selection
65   see further down for details
66
67 * uudec
68   WORKS ON: current message (or part of multipart message)
69   COMMAND: uudec %f&
70   Decode and display uuencoded images using uudecode.
71
72 * textviewer.sh
73   WORKS ON: current message part
74   COMMAND: textviewer.sh %p |
75   Attempt to view an attachment as plain text
76
77 * More action examples can be found at
78   http://melvin.hadasht.free.fr/home/sylpheed/actions/
79
80 ** multiwebsearch.pl **
81
82   WHAT IT DOES
83         This is an Actions script that allows you to search
84         websites for the selected text. It uses the default
85         Sylpheed-Claws browser as configured through Sylpheed
86         -Claws' GUI and specified in ~/.sylpheed-claws/sylpheedrc,
87         and a configuration file called multiwebsearch.conf.
88         
89   CONFIGURATION
90         The configuration file takes the following format:
91         
92         ALIAS|URL PART|URL PART
93         
94         ALIAS is a user-defined name; the first URL PART is the
95         url before the search term; the second URL PART is
96         optional and contains the remaining part of the url which
97         comes after the search term. A sample configuration file
98         is included.
99         
100   HOW TO USE IT
101         Copy 'multiwebsearch.conf' to ~/.sylpheed-claws/
102         
103         Configure an Action:
104         a) pre-configured website 
105            Command: multiwebsearch.pl --where="google" --what="%s"
106         b) dynamic
107            Command: multiwebsearch.pl --where="%u" --what="%s"
108            
109         In type a) "google" refers to one of the configured aliases,
110         this Action will always search the website referred to by
111         the alias "google".
112         
113         In type b) you will be presented with a dialog box into
114         which you type one of your configured aliases
115
116   
117   Contact: Paul Mangan <claws@thewildbeast.co.uk>
118 --------------------------------------------------------------------------------
119
120 Address book conversion
121 -----------------------
122
123 * eud2gc.py
124
125   WHAT IT DOES
126         This python-script is a quick hack to convert an Eudora (v.3?)
127         addressbook to vCard (GnomeCard) format.
128
129   HOW TO USE IT
130         You may do whatever you want with it! (Also regarding copying)
131         However, the script is intended to use like this:
132
133                 eud2gc.py <Eudora-addressbook-file> <Gnomecard-file>
134
135         Be careful not to overwrite your original GnomeCard.gcrd!
136         (But of course you might want to add the converted stuff to it)
137
138   Contact: Jeroen Versteeg <j.m.versteeg@student.utwente.nl>
139
140 * kmail2sylpheed.pl
141
142   WHAT IT DOES
143         This perl script will convert an exported Kmail addressbook into a
144         Sylpheed-Claws addressbook. If your version of Kmail is 1.37 or
145         greater and/or your version of KAddressBook is 3.1beta1 or greater,
146         or this script mixes up your definitions and their related data, use
147         'kmail2sylpheed_v2.pl' instead.
148
149   HOW TO USE IT
150         (You must run sylpheed-claws at least once before running this script.)
151
152         In Kmail's Address book choose '/File/Export List'. This will export
153         your Kmail address book data to a *.csv file.
154
155         If Sylpheed-Claws is running, close it.
156
157         From the command line, execute the following:
158  
159                 perl kmail2sylpheed.pl --kmailfile=/path/to/addressbook.csv
160
161         Your Kmail address book data will now be contained in Sylpheed-Claws'
162         address book, under the name 'Kmail Address Book'.
163
164   Contact: Paul Mangan <claws@thewildbeast.co.uk>
165     
166
167 * kmail2sylpheed_v2.pl
168
169   This script has been tested with Kmail 1.4.7 and KAddressBook 3.1beta1
170
171   WHAT IT DOES
172         This perl script will convert a Kmail address book that has been
173         exported in csv format into a Sylpheed-Claws address book.
174
175   HOW TO USE IT
176         (You must run sylpheed-claws at least once before running this script.)
177   
178         Open Kmail's Addressbook, /File/Address Book
179         In Kmail's Addressbook choose '/File/Export/Export List...'. This 
180         will allow you to export your Kmail addressbook data to a *.csv file.
181
182         If Sylpheed-Claws is running, close it.
183
184         From the command line, execute the following:
185  
186                 perl kmail2sylpheed_v2.pl --kmailfile=/path/to/addressbook.csv
187         
188         You can also use --help to see usage instructions.
189
190         Your Kmail addressbook data will now be contained in Sylpheed-Claws'
191         addressbook, under the name 'Kmail address book'.
192
193   Contact: Paul Mangan <claws@thewildbeast.co.uk>  
194
195
196 * outlook2sylpheed.pl
197
198   WHAT IT DOES
199         This perl script converts an Outlook generated contact list into a 
200         Sylpheed-Claws XML address book.
201
202   HOW TO USE IT
203         For text files:
204         --------------
205         You must export Outlook Express contact list as TXT file, choosing
206         only "Name" and "Address" fields to export.
207
208         You must exit Sylpheed-Claws before converting the contact list.
209
210         From the command line, execute the following:
211
212                 outlook2sylpheed.pl fullpathname
213
214         For csv files:
215         -------------
216         You must export Outlook contact list as CSV file, choosing ALL the
217         fields available for exporting.
218
219         You must exit Sylpheed-Claws before converting the contact list.
220
221         From the command line, execute the following:
222
223                 outlook2sylpheed.pl --csv fullpathname
224
225   LIMITATIONS
226         For text files only works with fields described above. If you have 
227         more complex examples send them to me, and I'll try to enhance the 
228         script.
229
230         For csv files you must export all fields (but only non empty fields
231         are added to the created Sylpheed-Claws address book) and the number
232         of fields expected is harcoded. Look for the $nboffields variable in
233         the script and change its value if you are sure you exported all
234         fields and script gives the 'unknown csv file format' error.
235
236   Contact: Ricardo Mones Lastra <mones@aic.uniovi.es>
237
238
239 * tb2sylpheed
240
241   WHAT IT DOES
242         This perl script will convert an address book exported from The Bat! 
243         into a Sylpheed-Claws address book.
244
245   HOW TO USE IT
246         (You must run sylpheed-claws at least once before running this script.)
247
248         If Sylpheed-Claws is running, close it.
249
250         Export The Bat! Address Book to CSV file format with all fields 
251         selected to YES and then start:
252
253                 tb2sylpheed --tbfile=/full/path/to/thebat/addressbook.csv
254  
255         The Bat! addressbook data will now be contained in Sylpheed-Claws'
256         addressbook, under the name 'The Bat! Address Book'.
257
258   Contact: Urke MMI <urke@gmx.net>  
259
260
261 * vcard2xml.py
262
263   WHAT IT DOES
264         This python script will convert an Evolution vCard into a Sylpheed-Claws
265         address book.
266
267   HOW TO USE IT
268         (You must run sylpheed-claws at least once before running this script.)
269
270         If Sylpheed-Claws is running, close it.
271         From the command line, execute the following:
272
273                 vcard2xml.py source_file [destination_file]
274  
275         When only <source_file> is specified it will overwrite (and
276         create a backup of) the existing addressbook. 
277         When both arguments are suplied it will create a new additional 
278         addressbook named as <destination_file>.
279         If the script encounters an error it will attempt to roll back
280         the changes and restore the original files.
281
282   Contact: Bogdan Sumanariu <bsumanariu@one5.ro> 
283
284 --------------------------------------------------------------------------------
285
286 Mailbox conversion
287 ------------------
288
289 * calypso_convert.pl
290
291   WHAT IT DOES
292         This perl script imports mbox files that are exported by Calypso.
293         It recreates the folder structure by scanning the "X-CalypsoFolder"
294         header and reincludes the attachments referenced in the
295         "X-CalypsoHtmlBody" "X-CalypsoAccount" "X-Attachment" headers.
296   
297   HOW TO USE IT
298         Export the Calypso mailbox by selecting "Save to archive" and check
299         the "Save attachments" box.
300         
301         Edit the script to set following variables (at the top of the file):
302            $mboxdir  : path to the exported mbox, e.g. 'Archive' or '.'
303            $mboxfile : name of exported mbox, e.g. 'mail.txt'
304            $outdir   : name of the MH folder to create, e.g. 'Calypso'
305            
306          Run the script using
307          
308                 perl calypso_convert.pl
309                 
310         Finally, import that folder by either selecting "New mailbox" or
311         moving it into your existing directory and recreate the folder
312         structure manually (contentmenu from folderview).
313
314   Contact: Thorsten Maerz <torte@netztorte.de>
315
316 * convert_mbox.pl
317
318   WHAT IT DOES
319         This perl script converts an mbox directory's contents into 
320         Sylpheed-Claws' MH format.
321   
322   HOW TO USE IT
323   
324         Run the script using:
325          
326                 perl convert_mbox.pl MBOX MH_DIR
327                 
328         Move the outputted MH_DIR and its contents into your Sylpheed-Claws
329         Mail folder; in Sylpheed-Claws right-click the top-level folder and
330         choose 'Rebuild folder tree' from the popup menu.
331
332   Contact: Fred Marton <Fred.Marton@uni-bayreuth.de>
333
334 * maildir2sylpheed.pl
335
336   WHAT IT DOES
337         This perl script converts a mailbox in maildir format into
338         Sylpheed-Claws' MH format.
339   
340   HOW TO USE IT
341   
342         Exit Sylpheed-Claws if running.
343         
344         Run the script using:
345          
346                 perl maildir2sylpheed.pl --kmaildir=mail_folder_name
347                 
348         Start Sylpheed-Claws and right-click the toplevel mailbox, i.e
349         "Mailbox (MH)", and select 'Rebuild folder tree'.
350         You may also need to run '/File/Folder/Check for new messages
351         in all folders'
352         Your maildir directory will be backed-up.
353         
354         Additional options:
355                 --debug         debug mode
356                 --dry-run       test mode, nothing is actually written
357                 --help          brief usage info
358         
359   Contact: Paul Mangan <claws@thewildbeast.co.uk>
360
361 * tbird2syl.py
362
363   WHAT IT DOES
364         This python script integrates a Thunderbird folder tree into 
365         Sylpheed-Claws.
366   
367   HOW TO USE IT
368   
369         The script receives two parameters from command-line:
370         <Thunderbird folder path> <Sylpheed folder path>
371
372         The best way to use it is to go to inside your Thunderbird
373         root mailfolder directory and invoke it as:
374
375                 <path>\python2.4 <path>\tbird2syl.py . <path to sylpheed>\Mail
376
377   Contact: Aleksandar Urosevic aka Urke MMI <urke@gmx.net>
378
379 --------------------------------------------------------------------------------
380
381 Other tools
382 -----------
383
384 * acroread2sylpheed.pl
385
386   WHAT IT DOES
387         This perl script enables Adobe Reader 7 to send documents to
388         Sylpheed-Claws as attachments.
389
390   HOW TO USE IT
391         Make sure that the script is executable (chmod +x acroread2sylpheed.pl)
392         Start up Adobe Reader 7 (acroread)
393         Go to /Edit/Preferences/SendMail
394         Select any email client except 'System Mail (mail)'
395         Enter the path to this script in the alternate location box  
396
397         You can then use 'File/Email' or the Email toolbar button to launch
398         sylpheed-claws (if not already launched) and open a new compose window
399         with the PDF attached.
400   
401   Contact: Paul Mangan <claws@thewildbeast.co.uk>
402
403
404 * filter_conv_new.pl
405
406   WHAT IT DOES
407         This perl script provides easy conversion of your filtering rules from
408         sylpheed's new filter system (>= 0.9.99) to the filtering system used in
409         sylpheed-claws. (Disabled rules are ignored)
410         It reads '~/.sylpheed-2.0/filter.xml' or '~/.sylpheed/filter.xml' and
411         writes '~/[CLAWS CONFIG DIR]/matcherrc'
412   
413   HOW TO USE IT
414         Issue the following command from the 'tools' directory:
415
416         perl filter_conv_new.pl
417
418         That's it, the claws' filtering system is now implemented with your
419         previous rules applied.
420
421   REQUIREMENTS
422         XML::SimpleObject
423
424   Contact: Paul Mangan <claws@thewildbeast.co.uk>
425   
426
427 * filter_conv.pl
428
429   WHAT IT DOES
430         This perl script provides easy conversion of your filtering rules
431         from sylpheed's old filter system (< 0.9.99) to the filtering system
432         used in sylpheed-claws.
433         It reads '~/.sylpheed/filterrc' and writes '~/.sylpheed-claws/matcherrc'
434   
435   HOW TO USE IT
436         Issue the following command from the 'tools' directory:
437
438         perl filter_conv.pl
439
440         That's it, the new filtering system is now implemented with your
441         previous rules applied.
442
443   Contact: Paul Mangan <claws@thewildbeast.co.uk>
444   
445
446 * nautilus2sylpheed.sh
447
448   WHAT IT DOES
449         This script will recursively attach a number of selected 
450         files/directories from Nautilus to a new blank e-mail.
451
452   HOW TO USE IT
453         Copy the script to $HOME/.gnome2/nautilus-scripts, chmod u+x, 
454         and restart nautilus (killall -9 nautilus). You will now have 
455         a right-click menu item: '/Scripts/nautilus2sylpheed.sh'
456         
457   Contact: Reza Pakdel <hrpakdel@cpsc.ucalgary.ca>
458
459
460 * OOo2sylpheed.pl
461
462   WHAT IT DOES
463         This perl script enables OpenOffice.org to send documents to
464         Sylpheed-Claws as attachments.
465
466   HOW TO USE IT
467     OpenOffice.org Version 2.0
468     ----------------------------
469         This script is not needed for OOo version 2, which can work
470         directly with Sylpheed-Claws.
471         Go to 'Tools/Options/Internet/E-mail' and enter 'sylpheed-claws'
472         in the box.
473
474     OpenOffice.org Version 1.1.0
475     ----------------------------
476         Start up OpenOffice.org.
477         Go to 'Tools/Options/OpenOffice.org/External Programs'
478         Select either ''Mozilla 1.x (Option 1)', or 
479         'Netscape 6.x - 7.0 (Option 1)' from the 'Program' selection
480         Enter the path to OOo2sylpheed.pl in the 'Path' box
481         or select it by clicking on the '...' button.
482     
483         You can then use 'File/Send/Document as email' to launch
484         sylpheed-claws (if not already launched) and open a new compose
485         window with the document attached.
486
487     OpenOffice.org Version 1.0
488     --------------------------
489         Start up OpenOffice.org.
490         Go to 'Tools/Options/OpenOffice.org/External Programs'
491         Enter the path to OOo2sylpheed.pl in the 'Program' box
492         or select it by clicking on the '...' button.
493
494
495   Contact: Paul Mangan <claws@thewildbeast.co.uk>
496
497
498 * update-po
499
500   WHAT IT DOES
501         This script is a message catalog translator's tool, it updates the .po 
502         files named on the command line.
503
504   HOW TO USE IT
505         This script needs to be copied to and run from the 'po' directory.
506   
507                 ./update-po lang.po lang2.po ...
508
509         to update one or more <yourlang>.po files from the sourcecode files
510          named in POTFILES.in. The old .po file is save in a .po.old file.
511
512         For example, when you want to update fr.po, run ./update-po fr.po, 
513         then edit fr.po to update your translation.
514
515   Contact: Wilbert Berendsen <wilbert@oswf.org>
516
517 --------------------------------------------------------------------------------
518
519 Extra tools
520 -----------
521
522 * gif2xface.pl
523
524   WHAT IT DOES
525         This perl script converts a monochrome (1 bit) 48x48 pixels GIF file
526         into an X-Face graphic suitable for inclusion into custom headers of
527         Sylpheed-Claws. An X-Face allows to quickly identify (or be identified
528         as) the sender of a mail message in a xface-capable MUA (like sylpheed
529         -claws).
530
531   HOW TO USE IT
532         After obtaining the desired image for your X-Face you should:
533           * scale it to 48x48 pixels (Image->Scale image on Gimp)
534           * down color depth to b/w (Image->Mode->Indexed selecting "Use
535             Black/White palette" and the desired dithering options (prior to
536             indexing doing Image->Colors->Threshold allows you to select the
537             b/w level if you don't want a dithered (dotty) image))
538           * save file as non-interlaced GIF
539         Then do:
540
541                 ./gif2xface < filename.gif > filename.xface
542
543         In filename.xface will be the X-Face header ready to use.
544         You can add a custom header in Sylpheed-Claws through Configuration->
545         Preferences per account, "Send" tab, check "Add user-defined header"
546         then "Edit..." if you want to add it via Sylpheed -Claws interface, or do
547
548                 echo "0:" `cat filename.xface` > ~/.sylpheed-claws/customheaderrc
549
550         if you want to create the custom headers file yourself (Warning: this
551         method is valid only if you don't have any other custom header set or
552         they will be lost!).
553
554   Contact: Ricardo Mones Lastra <mones@aic.uniovi.es>
555
556 --------------------------------------------------------------------------------