Re: docs-common Makefile.common,1.66,1.67

[Tommy Reynolds]

Uttered "Tommy Reynolds" (jtr) <fedora-docs-commits(a)redhat.com&gt;, spake
thus:

>  Modified Files:
>  	Makefile.common 
>  Log Message:
>  Revert prior changes.  Document template purpose. 
 
>  -PO2XML	=xml2po
>  +PO2XML	=po2xml 
>  
> #########################################################################
>  +# Define a template to generate the locale-specific XML files given the
>  +# original ${PRI_LANG} file and an updated po/${LANG}.po file.
>   define	XML_template
>   $(patsubst ${PRI_LANG}/%,${1}/%,${2}):: ${2} po/${1}.po ${1}
>  -	${PO2XML} -p po/${1}.po ${2} >$$@
>  +	${PO2XML} ${2} po/${1}.po >$$@
>   endef 
My sincere apologies for not describing my (mis)understanding of the
translation process earlier.  Below shows how I envisioned this process
working.  The file maintenance steps, at least, seem to be very automated; 
the translator need concentrate on editing either the .PO or .POT file and 
a single make(1) target: make html-${LANG} or make xml-${LANG}, at their
preference.

The steps involved in the .POT / .PO / .XML file maintenance are:

1) Produce original XML in a ${PRI_LANG} subdirectory.

2) The target "make pot" can be used to generate a single .POT file from
   all of the ${PRI_LANG} XML files.  The "make pot" gets run automatically
   when a ${PRI_LANG} file is changed and one of the following steps are used.
   The resulting file is the po/${DOCBASE}.pot file.

3) The target "make po" generates an updated po/${LANG}.po file whenever the
   .POT changes.  Translation entries from the .POT file are merged into the
   .PO file.  The "make pot" rule is run first if necessary.

4) The target "make xml-${LANG}" generates all the translated XML files into 
   the "${LANG}/" directory.  This is done by applying the .PO files against
   the ${PRI_LANG} XML files using po2xml(1).  The "make po" rule is run first
   if necessary.

5) The target "make html-${LANG}" renders the XML in ${LANG}/*.xml to produce
   translated HTML in a "${DOCBASE}-${LANG}/" folder.  The "make
xml-${LANG}"
   rule is run first if necessary.

So, as I (mis)understand the process, the very first action a translator
should take is to:

a) Add the appropriate locale to the ${OTHERS} list; and
b) "make po"
c) Insert translated entries into either the .PO or .POT file; the .PO file
   serves as the translation archive and is preserved across builds but the
   .POT file is rewritten every time the matching XML file changes.
d) "make xml-${LANG}" to view the applied XML translations.  The target
   "make html-${LANG}" should work equally well.

For later translation sessions, the translator repeats the steps:

I)    "make po"
II)   Insert translations into either the .PO or .POT file
III) "make xml-${LANG}" or "make html-${LANG}" as desired.

If this technique does not match the translator's expectations, we need to
adapt the process.

Cheers