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