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