ICU-8991 Added readme.txt to explain the instructions.

X-SVN-Rev: 31245

diff --git a/tools/currency/readme.txt b/tools/currency/readme.txt
new file mode 100644 (file)
index 0000000..c0d0154
--- /dev/null
+++ b/tools/currency/readme.txt
@@ -0,0 +1,117 @@
+*******************************************************************************
+* Copyright (C) 2012, International Business Machines Corporation and         *
+* others. All Rights Reserved.                                                *
+*******************************************************************************
+
+[Overview]
+
+This directory contains a tool used for maintaining ICU's ISO 4217 currency
+code mapping data. ICU uses a resource generated by this tool for mapping
+ISO 4217 currency alpha codes to numeric codes.
+
+
+[Files]
+
+package com.ibm.icu.dev.tool.currency
+
+Main.java - The tool's entry point
+NumericCodeData.java - The mapping data used by ICU
+CurrencyDataParser.java - ISO 4217 XML data parser
+CurrencyDataEntry.java - ISO 4217 XML data entry
+
+
+[Details]
+
+com.ibm.icu.dev.tool.NumericCodeData has String[][] CODE_MAP_DATA.
+This array represents mappings between ISO 4217 alpha codes and
+numeric codes. ICU's resource bundle currencyNumericCodes is generated
+from the table.
+
+ISO 4217 maintenance agency - SIX Interbank Clearing distributes
+ISO 4217 code data in XML format. These files are found in
+http://www.currency-iso.org/iso_index/iso_tables.htm. There are two
+files that we're interested in.
+
+ - http://www.currency-iso.org/dl_iso_table_a1.xml
+ - http://www.currency-iso.org/dl_iso_tables_a3.xml
+
+Table A.1 contains current currencies and funds and Table A.3 contains
+historic denominations.
+
+The tool supports 3 commands - check / print / build.
+
+1) check
+
+This command compares the hardcoded mapping data in NumericCodeData.java
+with the ISO 4217 XML data files side by side and check differences.
+
+2) print
+
+This command prints out body of String[][] CODE_MAP_DATA from the ISO
+4217 XML data files.
+
+3) build
+
+This command writes out the hardcoded mapping data in NumericCodeData.java
+in ICU resource bundle source format - currencyNumericCodes.txt.
+
+
+[Release Tasks]
+
+For each ICU release, we should check if the mapping data is up to date.
+
+Prerequisites: Java 6+, ant
+
+First, run the ant target "check". This ant target download XML files from
+the SIX Interbank Clearing site and invoke the tool command "check".
+
+When the target successfully finished, you should see the log like below:
+----------------------------------------------------------------------------
+C:\devtls\trunk\currency>ant check
+Buildfile: C:\devtls\trunk\currency\build.xml
+
+classes:
+
+_checkLocalXml:
+
+_localXml:
+
+_downloadXml:
+     [echo] Downloading ISO 4217 XML data files
+      [get] Getting: http://www.currency-iso.org/dl_iso_table_a1.xml
+      [get] To: C:\devtls\trunk\currency\out\xml\dl_iso_table_a1.xml
+      [get] Getting: http://www.currency-iso.org/dl_iso_tables_a3.xml
+      [get] To: C:\devtls\trunk\currency\out\xml\dl_iso_tables_a3.xml
+
+xmlData:
+
+check:
+     [java] [OK] ICU data is synchronized with the reference data
+
+BUILD SUCCESSFUL
+Total time: 2 seconds
+----------------------------------------------------------------------------
+In this case, our data is synchronized with the latest XML data and you're done.
+
+
+If the data is out of sync, you should see message like below:
+----------------------------------------------------------------------------
+check:
+     [java] Missing alpha code in ICU map [ZWR]
+     [java] Codes not found in the reference data: ZZZ
+
+BUILD FAILED
+C:\devtls\trunk\currency\build.xml:54: Java returned: 1
+----------------------------------------------------------------------------
+In this case, you have to update the hardcoded data in NumericCodeData.
+You can either edit the table in NumericCodeData manually, or run the tool
+command "print" and copy the output and paste it to the table.
+
+Once you make sure "ant check" returns no errors, run "ant build". This
+target generate out/res/currencyNumericCodes.txt. The file should go to
+<icu4c>/source/data/misc directory.
+
+Note: The default ant target does both operation. Although it creates the
+ICU resource file, you do not need to replace the one in ICU4C package with
+the newly generated one if "check" successfully finished.
+