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