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