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