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   newscache_clean.pl            Clean up news directory
  31   OOo2sylpheed.pl               Send documents from OpenOffice.org
  32   sylpheed-switcher             Run either sylpheed or claws (separate configs)
  33   sylprint.pl                   Printing engine, explained in README.sylprint
  34   update-po                     Update the .po files named on the command line.
  35
  36 Extra tools:
  37   gif2xface.pl                  Convert a 48x48 GIF file to an X-Face header
  38   launch_firebird               Open URLs in mozilla-firebird
  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 * newscache_clean.pl
 390
 391   WHAT IT DOES AND WHY IT DOES IT
 392         This perl script cleans up in '$HOME/.sylpheed/newscache'. Currently
 393         the newscache becomes littered with old directories and files - when
 394         you subscribe to a newsgroup a sub-directory gets created for it in
 395         ~/.sylpheed/newscache/[nntpserver], should you unsubscribe from the
 396         group the sub-directory does not get deleted. Until this is done
 397         internally this script will take care of some tidying up.
 398
 399         This script removes directory trees of nntp servers that you no longer
 400         have an account for. Where an account exists it removes directories
 401         and files of those groups to which you are no longer subscribed.
 402
 403   HOW TO USE IT
 404         Issue the following command from the 'tools' directory:
 405
 406                 perl newscache_clean.pl
 407
 408         This script uses the File::Path module, if you don't already have it
 409         installed, you can find it at the CPAN search site
 410         <http://search.cpan.org>
 411
 412   Contact: Paul Mangan <claws@thewildbeast.co.uk>
 413
 414
 415 * OOo2sylpheed.pl
 416
 417   WHAT IT DOES
 418         This perl script enables OpenOffice.org to send documents to sylpheed
 419         as attachments.
 420
 421   HOW TO USE IT
 422     OpenOffice.org Version 1.0
 423     --------------------------
 424         Start up OpenOffice.org.
 425         Go to 'Tools/Options/OpenOffice.org/External Programs'
 426         Enter the path to OOo2sylpheed.pl in the 'Program' box
 427         or select it by clicking on the '...' button.
 428
 429     OpenOffice.org Version 1.1.0
 430     ----------------------------
 431         Start up OpenOffice.org.
 432         Go to 'Tools/Options/OpenOffice.org/External Programs'
 433         Select either ''Mozilla 1.x (Option 1)', or
 434         'Netscape 6.x - 7.0 (Option 1)' from the 'Program' selection
 435         Enter the path to OOo2sylpheed.pl in the 'Path' box
 436         or select it by clicking on the '...' button.
 437
 438         You can then use 'File/Send/Document as email' to launch sylpheed
 439         (if not already launched) and open a new compose window with the
 440         document attached.
 441
 442         Tested with OpenOffice.org versions 1.0, 1.1.0
 443
 444   Contact: Paul Mangan <claws@thewildbeast.co.uk>
 445
 446
 447 * sylpheed-switcher
 448
 449   WHAT IT DOES
 450         This perl script is for users who like to move between the main
 451         sylpheed branch and the claws branch. Because of some differences
 452         between the stored options it is better IMO to use two separate
 453         '.sylpheed' directory trees. Doing that manually could prove to
 454         be tiresome, and so I've written this script to automate the task.
 455
 456         The first time you run this script you enter the full paths,
 457         including the executable itself, to both the main version of
 458         sylpheed and the claws version. This information is then stored
 459         in a file in your $HOME directory called '.sylpheed-switcher'
 460
 461         During this initial set-up, your '~/.sylpheed' directory
 462         is copied to '~/.sylpheed-main' and '~/.sylpheed-claws'.
 463
 464         When you run sylpheed via this script, your '~/.sylpheed' directory
 465         is deleted and replaced with a symbolic link to either
 466         ~/.sylpheed-main' or '~/sylpheed-claws', depending on the option you
 467         choose. (On subsequent usage the symbolic link is deleted and replaced
 468         with a new symbolic link).
 469
 470   HOW TO USE IT
 471         Initial set-up
 472         Enter the full paths to the executable, including the executable itself,
 473         example:
 474
 475                 ./sylpheed-switcher --claws-path=/usr/local/bin/sylpheed
 476                 --main-path=/usr/bin/sylpheed
 477
 478         After the initial set-up, use the following:
 479
 480                 ./sylpheed-switcher --claws     (to run sylpheed-claws)
 481                 ./sylpheed-switcher --main      (to run sylpheed main)
 482
 483         Additionally you can append --debug to run in debug mode.
 484         Use --help for more info.
 485
 486         This script uses the File::Path and Getopt::Long modules, if you don't
 487         already have them installed, you can find them at the CPAN search site
 488         <http://search.cpan.org>
 489
 490   Contact: Paul Mangan <claws@thewildbeast.co.uk>
 491
 492
 493 * update-po
 494
 495   WHAT IT DOES
 496         This script is a message catalog translator's tool, it updates the .po
 497         files named on the command line.
 498
 499   HOW TO USE IT
 500         This script needs to be copied to and run from the 'po' directory.
 501
 502                 ./update-po lang.po lang2.po ...
 503
 504         to update one or more <yourlang>.po files from the sourcecode files
 505          named in POTFILES.in. The old .po file is save in a .po.old file.
 506
 507         For example, when you want to update fr.po, run ./update-po fr.po,
 508         then edit fr.po to update your translation.
 509
 510   Contact: Wilbert Berendsen <wilbert@oswf.org>
 511
 512 --------------------------------------------------------------------------------
 513
 514 Extra tools
 515 -----------
 516
 517 * gif2xface.pl
 518
 519   WHAT IT DOES
 520         This perl script converts a monochrome (1 bit) 48x48 pixels GIF file
 521         into an X-Face graphic suitable for inclusion into custom headers of
 522         Sylpheed. An X-Face allows to quickly identify (or be identified as)
 523         the sender of a mail message in a xface-capable MUA (like sylpheed).
 524
 525   HOW TO USE IT
 526         After obtaining the desired image for your X-Face you should:
 527           * scale it to 48x48 pixels (Image->Scale image on Gimp)
 528           * down color depth to b/w (Image->Mode->Indexed selecting "Use
 529             Black/White palette" and the desired dithering options (prior to
 530             indexing doing Image->Colors->Threshold allows you to select the
 531             b/w level if you don't want a dithered (dotty) image))
 532           * save file as non-interlaced GIF
 533         Then do:
 534
 535                 ./gif2xface < filename.gif > filename.xface
 536
 537         In filename.xface will be the X-Face header ready to use.
 538         You can add a custom header in Sylpheed through Configuration->
 539         Preferences per account, "Send" tab, check "Add user-defined header"
 540         then "Edit..." if you want to add it via Sylpheed interface, or do
 541
 542                 echo "0:" `cat filename.xface` > ~/.sylpheed/customheaderrc
 543
 544         if you want to create the custom headers file yourself (Warning: this
 545         method is valid only if you don't have any other custom header set or
 546         they will be lost!).
 547
 548   Contact: Ricardo Mones Lastra <mones@aic.uniovi.es>
 549
 550
 551 * launch_firebird
 552
 553   WHAT IT DOES
 554         Check for a running mozilla-firebird process and and open a new tab
 555         with a given URL, or execute mozilla-firebird with that URL
 556
 557   HOW TO USE IT
 558         In Common Preferences move to the 'Other' tab and enter the
 559         following in the 'Web browser' box
 560
 561         launch_firebird '%s'
 562
 563   Contact: Mohammed Sameer <Uniball@linux-egypt.org>
 564
 565
 566 --------------------------------------------------------------------------------