buildxml: add comments

Signed-off-by: Osamu Aoki <osamu@debian.org>

bin/buildxml

@@ -1,14 +1,25 @@
 #!/bin/sh -e
+#
+# This is a build script for all *.xml data used by Makefile
+# This is smart enough
+#  * to skip po data for untranslated and
+#  * to use fall back translation for zh-cn/zh-tw
+#
+# List of translation languges as arguments
 LANGPO="$*"
+# Directory holding po data based on debian-reference.en.xmlt (persistent)
 DPO="po"
+# Directory holding po data applied to debian-reference.en.xml (temporary)
 DPOTMP="po-tmp"
 DBIN="bin"
+# data directory for opencc
 DCC="/usr/share/opencc"
 # The threshold should be 80 if translation is completed.
 MSGCAT="/usr/bin/msgcat"
+# command to auto-translate between zh-cn <-> zh-tw
 OPENCC="/usr/bin/opencc"
 
-# Generate PO (zh-cn)
+# Generate PO for zh-cn (use zh-tw as extra fallback data source with help of opencc)
 gen_po_zh_CN () {
     if [ -f ${OPENCC} ] ; then
         rm -f ${DPOTMP}/zh-cn.po
@@ -17,7 +28,7 @@ gen_po_zh_CN () {
     fi
 }
 
-# Generate PO (zh-tw)
+# Generate PO for zh-tw (use zh-cn as extra fallback data source with help of opencc)
 gen_po_zh_TW () {
     if [ -f ${OPENCC} ] ; then
         rm -f ${DPOTMP}/zh-tw.po
@@ -29,20 +40,24 @@ gen_po_zh_TW () {
 
 # build English source
 make debian-reference.en.xml
+# build English source (less non-translating strings to reduce po size)
 make debian-reference.en.xmlt
-# ensure POT is older
+# since po/debian-reference.pot is commited to git repo, no need to do this any more.
 #touch -t 200001010000.00 po/debian-reference.pot
-# update PO
+# set up po4a.cfg for po
 sed -e "s/@LANGPO@/${LANGPO}/" po4a.cfg.in > po4a.cfg
+# update po based on debian-reference.en.xmlt
 po4a -v --no-translations po4a.cfg
-# Fresh start
+# create po-tmp for debian-reference.en.xml
 rm -rf po-tmp
 cp -r po po-tmp
 gen_po_zh_CN
 gen_po_zh_TW
-# ensure to update pot 
+# set up po4a-tmp.cfg for po-tmp
 sed -e "s/@LANGPO@/${LANGPO}/" po4a-tmp.cfg.in > po4a-tmp.cfg
+# create empty pot in po-tmp with sure-to-be-older timestamp
 touch -t 200001010000.00 po-tmp/debian-reference.pot
+# update po-tmp data and build all translations based on debian-reference.en.xml
 po4a -v po4a-tmp.cfg
 #rm -rf po-tmp