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