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