From 99dd95f3c236bb48481199a1162bfefce3e31966 Mon Sep 17 00:00:00 2001
From: Edward Welbourne <edward.welbourne@qt.io>
Date: Tue, 23 May 2017 15:24:35 +0200
Subject: Document how to use the CLDR-related scripts

Say where to find the data, how to unpack it and how to run the
scripts to update our source tree from it.

Change-Id: I5b680090bb5850f29c1e7d61efd1d450856b9949
Reviewed-by: Lars Knoll <lars.knoll@qt.io>
---
 util/local_database/cldr2qlocalexml.py | 13 ++++++++++
 util/local_database/cldr2qtimezone.py  | 45 ++++++++++++++++++++--------------
 util/local_database/qlocalexml2cpp.py  |  8 +++++-
 3 files changed, 46 insertions(+), 20 deletions(-)

(limited to 'util')

diff --git a/util/local_database/cldr2qlocalexml.py b/util/local_database/cldr2qlocalexml.py
index 41cfafab0d..3d388118c3 100755
--- a/util/local_database/cldr2qlocalexml.py
+++ b/util/local_database/cldr2qlocalexml.py
@@ -26,6 +26,19 @@
 ## $QT_END_LICENSE$
 ##
 #############################################################################
+"""Convert CLDR data to qLocaleXML
+
+The CLDR data can be downloaded from CLDR_, which has a sub-directory
+for each version; you need the ``core.zip`` file for your version of
+choice (typically the latest).  This script has had updates to cope up
+to v29; for later versions, we may need adaptations.  Unpack the
+downloaded ``core.zip`` and check it has a common/main/ sub-directory:
+pass the path of that sub-directory to this script as its single
+command-line argument.  Save its standard output (but not error) to a
+file for later processing by ``./qlocalexml2cpp.py``
+
+.. _CLDR: ftp://unicode.org/Public/cldr/
+"""
 
 import os
 import sys
diff --git a/util/local_database/cldr2qtimezone.py b/util/local_database/cldr2qtimezone.py
index 502ab92fd5..bf30e39910 100644
--- a/util/local_database/cldr2qtimezone.py
+++ b/util/local_database/cldr2qtimezone.py
@@ -26,25 +26,32 @@
 ## $QT_END_LICENSE$
 ##
 #############################################################################
-
-
-# Script to parse the CLDR supplemental/windowsZones.xml file and encode for use in QTimeZone
-# XML structure is as follows:
-#
-# <supplementalData>
-#     <version number="$Revision: 7825 $"/>
-#     <generation date="$Date: 2012-10-10 14:45:31 -0700 (Wed, 10 Oct 2012) $"/>
-#     <windowsZones>
-#         <mapTimezones otherVersion="7dc0101" typeVersion="2012f">
-#             <!-- (UTC-08:00) Pacific Time (US & Canada) -->
-#             <mapZone other="Pacific Standard Time" territory="001" type="America/Los_Angeles"/>
-#             <mapZone other="Pacific Standard Time" territory="CA"  type="America/Vancouver America/Dawson America/Whitehorse"/>
-#             <mapZone other="Pacific Standard Time" territory="MX"  type="America/Tijuana"/>
-#             <mapZone other="Pacific Standard Time" territory="US"  type="America/Los_Angeles"/>
-#             <mapZone other="Pacific Standard Time" territory="ZZ"  type="PST8PDT"/>
-#       </mapTimezones>
-#     </windowsZones>
-# </supplementalData>
+"""Parse CLDR data for QTimeZone use with MS-Windows
+
+Script to parse the CLDR supplemental/windowsZones.xml file and encode
+for use in QTimeZone.  See ``./cldr2qlocalexml.py`` for where to get
+the CLDR data.  Pass its common/ directory as first parameter to this
+script and the qtbase root directory as second parameter.  It shall
+update qtbase's src/corelib/tools/qtimezoneprivate_data_p.h ready for
+use.
+
+The XML structure is as follows:
+
+ <supplementalData>
+     <version number="$Revision: 7825 $"/>
+     <generation date="$Date: 2012-10-10 14:45:31 -0700 (Wed, 10 Oct 2012) $"/>
+     <windowsZones>
+         <mapTimezones otherVersion="7dc0101" typeVersion="2012f">
+             <!-- (UTC-08:00) Pacific Time (US & Canada) -->
+             <mapZone other="Pacific Standard Time" territory="001" type="America/Los_Angeles"/>
+             <mapZone other="Pacific Standard Time" territory="CA"  type="America/Vancouver America/Dawson America/Whitehorse"/>
+             <mapZone other="Pacific Standard Time" territory="MX"  type="America/Tijuana"/>
+             <mapZone other="Pacific Standard Time" territory="US"  type="America/Los_Angeles"/>
+             <mapZone other="Pacific Standard Time" territory="ZZ"  type="PST8PDT"/>
+       </mapTimezones>
+     </windowsZones>
+ </supplementalData>
+"""
 
 import os
 import sys
diff --git a/util/local_database/qlocalexml2cpp.py b/util/local_database/qlocalexml2cpp.py
index 9fd88c46fe..3a2db1580d 100755
--- a/util/local_database/qlocalexml2cpp.py
+++ b/util/local_database/qlocalexml2cpp.py
@@ -26,6 +26,12 @@
 ## $QT_END_LICENSE$
 ##
 #############################################################################
+"""Script to generate C++ code from CLDR data in qLocaleXML form
+
+See ``cldr2qlocalexml.py`` for how to generate the qLocaleXML data itself.
+Pass the output file from that as first parameter to this script; pass
+the root of the qtbase check-out as second parameter.
+"""
 
 import os
 import sys
@@ -454,7 +460,7 @@ def currencyIsoCodeData(s):
     return "0,0,0"
 
 def usage():
-    print "Usage: qlocalexml2cpp.py <path-to-locale.xml> <path-to-qt-src-tree>"
+    print "Usage: qlocalexml2cpp.py <path-to-locale.xml> <path-to-qtbase-src-tree>"
     sys.exit(1)
 
 GENERATED_BLOCK_START = "// GENERATED PART STARTS HERE\n"
-- 
cgit v1.2.3