Update script and doc from web's tools dir
[claws.git] / tools / README
index 6b988e03101859b2590b14690310e27ec2d23732..c6310b5506063c53692da17027afc784c316b6c1 100644 (file)
@@ -4,6 +4,8 @@ Contents of the tools directory:
 --------------------------------------------------------------------------------
 
 Action scripts:
+  cm-reparent.pl                Fix thread parenting for two or more messages
+  cm-break.pl                   Remove thread parenting for one or more messages
   freshmeat_search.pl           Search freshmeat.net for selected text
   google_msgid.pl               Search groups.google.com for selected message-id
   google_search.pl              Search google.com for selected text
@@ -14,6 +16,8 @@ Action scripts:
                                 OpenOffice
 
 Addressbook conversion:
+  csv2addressbook.pl           Import Becky, Thunderbird, Kmail, Gmail and Fox
+                               Mail address books
   eud2gc.py                     Convert Eudora address book to Gnomecard
   kmail2claws-mail.pl           Import a Kmail address book (KDE2)
   kmail2claws-mail_v2.pl        Import a Kmail address book (KDE3)
@@ -57,10 +61,15 @@ Detailed Descriptions:
 Action scripts
 --------------
 
-* freshmeat_search.pl
-  WORKS ON: selection
-  COMMAND: |freshmeat_search.pl
-  Search freshmeat.net for selected text using the default Claws Mail browser
+* cm-reparent.pl
+  WORKS ON: selected messages (two or more)
+  COMMAND: cm-reparent.pl %F
+  Thread the selected messages based on date, old to new
+
+* cm-break.pl
+  WORKS ON: selected messages (one or more)
+  COMMAND: cm-break.pl %F
+  Break thread references for the selected messages
 
 * google_msgid.pl
   WORKS ON: selection
@@ -138,6 +147,86 @@ Action scripts
 Address book conversion
 -----------------------
 
+* csv2addressbook.pl
+
+  WHAT IT DOES
+       This perl script will import a Becky, Thunderbird, Kmail, Gmail and
+       Fox Mail address book.
+
+  HOW TO USE IT
+       (You must run claws-mail at least once before running this script.)
+
+       Becky >= 2.41
+       -------------
+       In Becky you need to do a CSV full export with titles of your
+       address book.
+
+       Run the script with the following options:
+
+       perl csv2addressbook.pl --type=becky --csv=/full/path/to/file.csv
+
+       Addtionally you can use the option '--name="My address book"', if
+       you don't use this option the new Claws address book will be
+       called 'Becky address book'.
+
+
+       Thunderbird >= 2.0.0.6
+       ----------------------
+       In Thunderbird you need to export your address book as 'comma
+       separated'.
+
+       Run the script with the following options:
+
+       perl csv2addressbook.pl --type=thunderbird --csv=/full/path/to/file.csv
+
+       Addtionally you can use the option '--name="My address book"', if
+       you don't use this option the new Claws address book will be
+       called 'Thunderbird address book'.
+
+       Kmail >= 1.9.7 / Kaddressbook >= 3.5.7
+       --------------------------------------
+       In Kaddressbook you need to export your address book as 'CSV List'.
+
+       Run the script with the following options:
+
+       perl csv2addressbook.pl --type=kmail --csv=/full/path/to/file.csv
+
+       Addtionally you can use the option '--name="My address book"', if
+       you don't use this option the new Claws address book will be
+       called 'Kmail address book'.
+
+       WARNING: Kmail/Kaddressbook has a bug whereby it exports badly
+       formatted CSV if the values are quoted.
+
+       Gmail
+       -----
+       In the Gmail web interface you need to export your address book
+       as Outlook CSV format.
+
+       Run the script with the following options:
+
+       perl csv2addressbook.pl --type=gmail --csv=/full/path/to/file.csv
+
+       Addtionally you can use the option '--name="My address book"', if
+       you don't use this option the new Claws address book will be
+       called 'gmail address book'.
+
+       Fox Mail
+       --------
+       Export your Fox Mail address book as CSV with all possible headers.
+
+       Run the script with the following options:
+
+       perl csv2addressbook.pl --type=foxmail --csv=/full/path/to/file.csv
+
+       Addtionally you can use the option '--name="My address book"', if
+       you don't use this option the new Claws address book will be
+       called 'foxmail address book'.
+
+       You can also run the script with '--help' to get a brief usage message.
+
+  Contact: Paul Mangan <paul@claws-mail.org>
+
 * eud2gc.py
 
   WHAT IT DOES
@@ -272,7 +361,7 @@ Address book conversion
        the script and change its value if you are sure you exported all
        fields and script gives the 'unknown csv file format' error.
 
-  Contact: Ricardo Mones Lastra <mones@aic.uniovi.es>
+  Contact: Ricardo Mones <ricardo@mones.org>
 
 
 * tb2claws-mail
@@ -442,18 +531,21 @@ Other tools
   WHAT IT DOES
        This script enables inserting files into the message body of a new 
        Claws Mail Compose window from the command line. Additionally To,
-       Cc, Subject and files to attach to the message can be specified. 
+       Cc, Bcc, Subject and files to attach to the message can be specified. 
 
   HOW TO USE IT
        claws-mail-compose-insert-files.pl [options]
        Options:
-               --help -h
-               --to mail@address.net[,mail2@address.net]
-               --cc mail@address.net[,mail2@address.net]
-               --subject "My subject"
-               --attach FILE
-               --insert FILE
-
+               --help -h
+               --to "Person One <mail@address.net>"
+               --cc "Person One <mail@address.net>"
+                       --bcc "Person One <mail@address.net>"
+               --subject "My subject"
+               --attach FILE
+               --insert FILE
+
+       For multiple recipients separate the addresses with ','
+       e.g. --to "Person One <mail@address.net>,Person Two <mail2@address.net>"
        --attach and --insert can be used multiple times
   
   Contact: Paul Mangan <paul@claws-mail.org>
@@ -500,20 +592,33 @@ Other tools
   Contact: Paul Mangan <paul@claws-mail.org>
   
 
-* fix-date.sh
+* fix_date.sh
 
- WHAT IT DOES
-       It will replace the Date: value w/ the one picked up from
-       more recent Received: field if this field resides in one
-       line. Otherwise, it will take the file modification time
-       (using a RFC 2822-compliant form). If no X-Original-Date already
-       exist, the former Date value will be set in such field.
+  Add a 'Date:' header to the selected email(s) when such header is
+  missing.  The correct date is guessed from other headers that
+  contain timestamp information (preferred: Fetchinfo header if found)
+  or from the file or system date as a fallback. The order or
+  preference for the date value replacement can be changed by editing
+  the script.
 
-  HOW TO USE IT
-       fix_date.sh <filename> [<filename>..]
+  This script can be used to fix messages that show non RFC-compliant
+  Date headers as well.
 
-  Contact: wwp <wwp@claws-mail.org>
+  X-Original-Date is always added too if not already existing (if so,
+  it's left untouched), to keep track of the original value if any.
 
+  An existing Date: header is not overwritten unless you use the
+  --force switch.
+
+  Non RFC-compliant dates can be overwritten using the --rfc switch.
+  Use --strict to use strict RFC matching patterns for date values in
+  other headers.
+
+  WORKS ON: selected message(s)
+
+  COMMAND: fix_date.sh %F
+
+  CONTACT: wwp <wwp@claws-mail.org>
 
 * mairix.sh
 
@@ -605,19 +710,26 @@ Other tools
 
   WHAT IT DOES
        This script tries to recognise an attachment by using the 'file'
-       command and/or the file extension and then uses the available Linux
-       utilities to make an effort to display it as text. For example
-               .doc                    antiword -w 72
-               .txt, .diff, .c, .h,
-                 .ic. .ec, .cc, .sh,
-                 .sed, .awk            cat
-               .html                   txt2htm or text2html
-               .xls, .sxc, .csv        xlscat -L
-               .rtf                    rtf2text
-               .pdf                    pdf2text %f -
-               .odt                    ooo2txt
-               .pl, .pm                perltidy -st -se or  cat
-               .bz2                    bzip2 -d < %f | strings
+       command and/or the file extension and then uses the available
+       utilities to make an effort to display it as text.
+
+       $ textview.pl --list
+
+       will show available conversion, the top:
+
+         .awk          cat
+         .bin          strings
+         .bz2          bzip2 -d < %f | strings
+         .c            cat
+         .cc           cat
+         .csv          xlscat -L
+
+       If there are multiple alternatives available, they are listed in
+       the ordder they are tried, like for .xls:
+
+         .xls          xlscat -L
+         .xls          catdoc -x -dutf-8
+         .xls          wvText
 
   HOW TO USE IT
        Go to /Configuration/Message View/External Programs and enter the
@@ -625,7 +737,10 @@ Other tools
        Now when you right-click an attachment and choose 'Display as text'
        this script will be invoked.
 
-       
+       xlscat comes with the perl module Spreadsheet::Read, which is a
+       wrapper module over several parsers and supports ods, sxc, csv, xls,
+       xlsx, and sq.  See https://metacpan.org/release/Spreadsheet-Read
+
   Contact: H.Merijn Brand <h.m.brand@xs4all.nl>
 
 
@@ -704,7 +819,7 @@ Extra tools
        method is valid only if you don't have any other custom header set or
        they will be lost!).
 
-  Contact: Ricardo Mones Lastra <mones@aic.uniovi.es>
+  Contact: Ricardo Mones <ricardo@mones.org>
 
 
 * update-po
@@ -727,3 +842,54 @@ Extra tools
   Contact: Wilbert Berendsen <wilbert@oswf.org> or the Claws Mail Team
 
 --------------------------------------------------------------------------------
+This file is Copyright 1999-2014 by the Claws Mail team.
+See accompanying COPYING file for license details.
+See each included script for copyright and license details.
+
+* cm-reparent.pl
+
+  WHAT IT DOES
+       This script tries to fix thread parenting for two or more messages
+
+  HOW TO USE IT
+       Define an action as
+
+         Menu name:  Reparent (fix threading)
+         Command:    cm-reparent.pl %F
+
+       Then select from the message list all files that should be re-parented
+
+       Then invoke the action
+
+  MORE INFORMATION
+       $ perldoc cm-reparent.pl
+
+  REQUIREMENTS
+       Date::Parse
+       Getopt::Long
+
+  Contact: H.Merijn Brand <h.m.brand@xs4all.nl>
+
+* cm-break.pl
+
+  WHAT IT DOES
+       This script tries to break thread parenting for one or more messages
+
+  HOW TO USE IT
+       Define an action as
+
+         Menu name:  Unthread (break threading)
+         Command:    cm-break.pl %F
+
+       Then select from the message list all files that should be un-threaded
+
+       Then invoke the action
+
+  MORE INFORMATION
+       $ perldoc cm-break.pl
+
+  REQUIREMENTS
+       Date::Parse
+       Getopt::Long
+
+  Contact: H.Merijn Brand <h.m.brand@xs4all.nl>