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