Reorganize the CVS layout to fully embrace I18N translator support.

Many, many changes here.  Refer to "example-tutorial/" for a model.

1)  Only one rpm-info.xml file, and that is in the top-level dir.
2)  XML file names are now language independant (para.xml, not
    para-en.xml).
3)  The "Makefile" in the document directory has been completely
    rewritten.  Now, a ${PRI_LANG} variable identifies the original
    language for the document.  Additional language translations are
    listed in the ${OTHERS} macro.  The ${XMLEXTRAFILES-${LANG}}
    variable is no more; instead an XMLFILES_template must be filled
    out to enumerate the necessary XML files.
4)  Translated XML files are automatically generated from .POT and
    .PO files located in a "po/" directory.
5)  Translated XML files should NOT be archived in CVS, since they
    are now generated files.
6)  Many new virtual targets have been added to "Makefile.common",
    such as "make xml-de", "make po-de", and the like.  Consult the
    "Makefile.common".

2 files changed, 227 insertions, 72 deletions

diff --git a/Makefile.common b/Makefile.common
index ad341b5..dd477a3 100644
--- a/Makefile.common
+++ b/Makefile.common
@@ -14,15 +14,27 @@
 # ${DOCNAME}.pdf	-- Builds PDF version of document
 # pdf			-- See "${DOCNAME}.pdf"
 #########################################################################
+
+#########################################################################
 # PDF generation is still fragile and probably won't work on your document.
 # Yet.
 #########################################################################
+
+#########################################################################
 # Note: all targets within this Makefile.common must be defined as 
 # double-colon (::) targets so that additional steps can be added by
 # providing additional rules, also marked with double-colons, in the
 # document Makefile.
 #########################################################################
-# N.B.: Don't use "$@" in a template.  It doesn't work.  I tried ;-(
+
+#########################################################################
+# N.B., if you want to use built-in variables such as "$@" in a template
+# be sure to quote them as "$$@" since the template is evaluated once as
+# it is expanded
+#########################################################################
+
+#########################################################################
+# WARNING.  This feature is deprecated and will shortly disappear.
 #########################################################################
 # Allow client document to provide "Make.paths" file to locate our files
 # This is a "silent include", so if it's missing there is no problem.
@@ -31,6 +43,8 @@
 # command line will take precedence.
 sinclude Make.paths
 #########################################################################
+
+#########################################################################
 # Supply default values for the boilerplate files _unless_ the user has
 # provided their own values.
 ifeq	"${FDPDIR}" ""
@@ -58,9 +72,7 @@ ifeq	"${PRI_LANG}" ""
 PRI_LANG= en
 endif
 ifeq	"${RPMINFO}" ""
-# Don't panic, we need this only to get the latest RPM package version
-# All other rpm-info usages are driven by XSLT scripts.
-RPMINFO		= ${PWD}/${PRI_LANG}/rpm-info-${PRI_LANG}.xml
+RPMINFO		= ${PWD}/rpm-info.xml
 endif
 ifeq	"${RPMPREP}" ""
 RPMPREP=yes
@@ -69,28 +81,44 @@ ifeq	"${RPMPOST}" ""
 RPMPOST=yes
 endif
 #########################################################################
-# Define a macro to locate xmlto(1) so we can choose a specific version
-# by "make XMLTO=/path/to/xmlto", if we so desire.
+
+#########################################################################
+# Strange though it may seem, some shells do not provide a ${PWD} 
+# environment variable for us.
+PWD	:=$(shell /bin/pwd)
+#########################################################################
+
+#########################################################################
+# Use macros to locate our commonly-used programs
 XMLTO	=xmlto
-# Let's also do this for xsltproc(1).
 XSLTPROC=xsltproc
 XMLFORMAT=xmlformat
 XMLFOPTS=-f $(FDPDIR)/docs-common/bin/xmlformat-fdp.conf
 XML2PO	=xml2po
+PO2XML	=po2xml
+MSGMERGE=msgmerge
+#########################################################################
+
 #########################################################################
 # Rules to produce .po files from .xml files.  Get the tools to do this
 # from the gnome-doc-utils RPM.
-.SUFFIXES: .po .xml
+.SUFFIXES: .po .pot .xml
 %.po:	%.xml
 	${XML2PO} $< >$@
 #########################################################################
+
+#########################################################################
 # Use our very own "docs-common/bin/fdpsh" as the command interpreter
 # This automatically has ${FDPBIN} as first in the ${PATH}
 SHELL	=${FDPBIN}/fdpsh
 #########################################################################
+
+#########################################################################
+# Obtain the document version and release info for building RPM's
 VERSION:=$(shell version doc)
 RELEASE:=$(shell version rpm)
-PWD	:=$(shell /bin/pwd)
+#########################################################################
+
 #########################################################################
 RPMFLAGS=--define "docbase $(DOCBASE)" 					\
 	 --define "_topdir $(PWD)/rpm" 					\
@@ -102,10 +130,24 @@ ifeq	"${RPMDEBUG}" "1"
 RPMDFLAG	= -vv
 endif
 #########################################################################
+
+#########################################################################
 # Set a provisional ${LANG} value.  We'll dynamically change this as 
-# needed.  The "en" value is used because that is the original language
-# of most of our current documentation.
-LANG	=en
+# needed.  The "${PRI_LANG}" value is used because that is the original 
+# language the doc.
+LANG	=${PRI_LANG}
+LANGUAGES=${PRI_LANG} ${OTHERS}
+#
+#########################################################################
+
+#########################################################################
+# Expand the template the XMLFILES_template to produce XMLFILES-${LANG}
+# macros that enumerate all of the input files for the document.
+
+$(foreach L,${LANGUAGES},$(eval $(call XMLFILES_template,${L})))
+#
+#########################################################################
+
 #########################################################################
 # PUT NO TARGETS BEFORE THIS ONE, not even in your base Makefile
 # In a properly-constructed Makefile, this will be the default target
@@ -113,6 +155,9 @@ LANG	=en
 TARGETS=all clean distclean fdp-info html html-nochunks pdf po showvars \
         tarball rpm rpm-common noarch srpm package-prep package-post	\
 	src-tarball
+
+# FIXME: add the .PHONY attribute where the actual target is defined
+
 .PHONY:	${TARGETS}
 .PHONY:	$(foreach LANG,${LANGUAGES},html-${LANG})
 .PHONY:	$(foreach LANG,${LANGUAGES},html-nochunks-${LANG})
@@ -123,6 +168,12 @@ all::	html html-nochunks tarball # pdf
 ${TARGETS}::
 
 #########################################################################
+# Ensure all 'clean' targets are invoked before 'distclean' targets
+distclean:: clean
+#
+#########################################################################
+
+#########################################################################
 # For each LANG in LANGUAGES, generate a target and rule similar to:
 # mydoc-en/index.html:: mydoc-en.xml ${XMLEXTRAFILES}-en
 #  LANG=en.UTF-8 ${XMLTO} html -x $(XSLHTML) -o mydoc-en mydoc-en.xml
@@ -135,102 +186,182 @@ ${TARGETS}::
 # but we do avoid copying EPS files since they are nonsense to the HTML world.
 #
 define	HTML_template
-html-$(1) ${DOCBASE}-$(1)/index.html:: $(1)/${DOCBASE}-$(1).xml $$(XMLEXTRAFILES-$(1)) $(1)/fdp-info-$(1).xml
-	LANG=$(1).UTF-8 ${XMLTO} html -x $(XSLHTML) -o $(DOCBASE)-$(1) $(1)/$(DOCBASE)-$(1).xml
+.PHONY:	html-${1}
+html-$(1) ${DOCBASE}-$(1)/index.html:: ${XMLFILES-${1}} $(1)/fdp-info.xml
+	LANG=$(1).UTF-8 ${XMLTO} html -x $(XSLHTML) -o $(DOCBASE)-$(1) $(1)/$(DOCBASE).xml
 	mkdir -p $(DOCBASE)-$(1)/stylesheet-images/
 	cp ${FDPDIR}/docs-common/stylesheet-images/*.png $(DOCBASE)-$(1)/stylesheet-images
 	cp ${HTMLCSS} $(DOCBASE)-$(1)/fedora.css
 ifeq	"${DRAFT}" "yes"
-	cp ${FDPDIR}/docs-common/images/watermark-$(1).png $(DOCBASE)-$(1)/watermark.png
+	cp ${FDPDIR}/docs-common/images/watermark-$(1).png 		\
+		$(DOCBASE)-$(1)/watermark.png
 endif
 	[ ! -d figs ] || copy-figs -v -f '*.png' 			\
 				-l $(1) figs $(DOCBASE)-$(1)
+
+distclean::
+	${RM} -r ${DOCBASE}-${1}
 endef
-#
-$(foreach LANG,${LANGUAGES},$(eval $(call HTML_template,${LANG})))
 
-html::	$(foreach LANG,${LANGUAGES},html-${LANG})
+$(foreach L,${LANGUAGES},$(eval $(call HTML_template,${L})))
+
+.PHONY:	html
+
+html::	$(foreach L,${LANGUAGES},html-${L})
 #
 #########################################################################
+
+#########################################################################
 # For each language in ${LANGUAGES}, generate a single HTML file
 define	HTMLNOCHUNK_template
-html-nochunks-$(1) ${DOCBASE}-$(1).html::	$(1)/${DOCBASE}-$(1).xml $$(XMLEXTRAFILES-$(1)) $(1)/fdp-info-$(1).xml
-	${XMLTO} html-nochunks -x $(XSLHTMLNOCHUNKS) $(1)/$(DOCBASE)-$(1).xml
+.PHONY:	html-nochunks-${1}
+
+html-nochunks-$(1) ${DOCBASE}-$(1).html:: ${XMLFILES-${1}} $(1)/fdp-info.xml
+	${XMLTO} html-nochunks -x $(XSLHTMLNOCHUNKS) $(1)/$(DOCBASE).xml
 	mkdir -p stylesheet-images/
 	cp ${FDPDIR}/docs-common/stylesheet-images/*.png stylesheet-images/
 	cp ${HTMLCSS} fedora.css
-	[ -z "${HTMLCSSEXTRA}" ] || 					\
-		cp ${HTMLCSSEXTRA} watermark.png
+ifeq	"${DRAFT}" "yes"
+	cp ${FDPDIR}/docs-common/images/watermark-$(1).png watermark.png
+endif
+
+distclean::
+	${RM} ${DOCBASE}-${1}.html
+	${RM} -r stylesheet-images
+	${RM} fedora.css
+	${RM} watermark.png
 endef
-#
-$(foreach LANG,${LANGUAGES},$(eval $(call HTMLNOCHUNK_template,${LANG})))
 
-html-nochunks::	$(foreach LANG,${LANGUAGES},html-nochunks-$(LANG))
+$(foreach L,${LANGUAGES},$(eval $(call HTMLNOCHUNK_template,${L})))
+
+.PHONY:	html-nochunks
+
+html-nochunks::	$(foreach L,${LANGUAGES},html-nochunks-$(L))
 #
 #########################################################################
+
+#########################################################################
 # For each language in ${LANGUAGES}, build a tarball of the HTML and
 # image files.  Any ".eps" files are ignored.
 #
 define	HTMLTAR_template
 ${DOCBASE}-$(1).tar.gz:: ${DOCBASE}-$(1)/index.html
 	tar -zc --exclude '*.eps' -f ${DOCBASE}-$(1).tar.gz ${DOCBASE}-$(1)
+
+distclean::
+	${RM} ${DOCBASE}-${1}.tar.gz
 endef
-#
-tarball::	$(foreach LANG,${LANGUAGES},$(DOCBASE)-$(LANG).tar.gz)
 
-$(foreach LANG,${LANGUAGES},$(eval $(call HTMLTAR_template,${LANG})))
+$(foreach L,${LANGUAGES},$(eval $(call HTMLTAR_template,${L})))
+
+.PHONY:	tarball
+
+tarball::	$(foreach LANG,${LANGUAGES},$(DOCBASE)-$(LANG).tar.gz)
 #
 #########################################################################
+
+#########################################################################
 # For each language in ${LANGUAGES}, generate an Adobe Portable Document
 # Format (PDF) file.
 define	PDF_template
-pdf-$(1) ${DOCBASE}-$(1).pdf:: $(1)/${DOCBASE}-$(1).xml $$(XMLEXTRAFILES-$(1))
+.PHONY:	pdf-${1}
+
+pdf-$(1) ${DOCBASE}-$(1).pdf:: ${XMLFILES-${1}} ${1}/fdp-info.xml
 	${XMLTO} pdf -x $(XSLPDF) $(1)/$(DOCBASE)-$(1).xml
+
+distclean::
+	${RM} ${DOCBASE}-${1}.pdf
 endef
-#
-$(foreach LANG,${LANGUAGES},$(eval $(call PDF_template,${LANG})))
+
+$(foreach L,${LANGUAGES},$(eval $(call PDF_template,${L})))
+
+.PHONY:	pdf
 
 pdf::	$(foreach LANG,${LANGUAGES},pdf-$(LANG))
 #
 #########################################################################
-# For each language in ${LANGUAGES}, clean up!
-define	CLEAN_template
-${DOCBASE}-$(1)-clean::
-	${RM} $(1)/fdp-info-$(1).xml
-endef
-#
-$(foreach LANG,${LANGUAGES},$(eval $(call CLEAN_template,${LANG})))
-#
-clean:: $(foreach LANG,${LANGUAGES},${DOCBASE}-${LANG}-clean)
+
+#########################################################################
+clean:: 
 	${RM} *.tmp
 #########################################################################
-define	DISTCLEAN_template
-${DOCBASE}-$(1)-distclean:: ${DOCBASE}-$(1)-clean
-	${RM} -r ${DOCBASE}-$(1)
-	${RM} -r ${DOCBASE}-$(1).html stylesheet-images
-	${RM} -r ${DOCBASE}-$(1).pdf
-	${RM} -r ${DOCBASE}-$(1).tar.gz
-	${RM} *-$(1).omf
-	${RM} *-$(1).desktop
-	${RM} fedora.css watermark-${LANG}.png watermark.png
-	${RM} $(1)/*.po
+
+#########################################################################
+po/${DOCBASE}.pot:: ${XMLFILES-${PRI_LANG}}
+	[ -d po ] || (echo ADD po/ TO CVS >&2; exit 1)
+	${XML2PO} -o $@ $^
+
+.PHONY:	pot
+
+pot::	po/${DOCBASE}.pot
+#########################################################################
+
+#########################################################################
+define	XML_template
+$(patsubst ${PRI_LANG}/%,${1}/%,${2}):: ${2} po/${1}.po
+	mkdir -p ${1}
+	${PO2XML} ${2} po/${1}.po >$$@
 endef
-#
-$(foreach LANG,${LANGUAGES},$(eval $(call DISTCLEAN_template,${LANG})))
-#
-distclean:: $(foreach LANG,${LANGUAGES},${DOCBASE}-${LANG}-distclean)
+
+$(foreach L,${OTHERS},							\
+	$(foreach F,${XMLFILES-${PRI_LANG}},				\
+		$(eval $(call XML_template,${L},${F}))))
+
+define	XMLTARGET_template
+.PHONY:	xml-${1}
+
+xml-${1}::	${XMLFILES-${1}}
+
+distclean::
+	${RM} -r ${1}
+endef
+
+.PHONY:	xml-${PRI_LANG}
+
+xml-${PRI_LANG}:: ${XMLFILES-${PRI_LANG}}
+
+$(foreach L,${OTHERS},$(eval $(call XMLTARGET_template,${L})))
+
+.PHONY:	xml-all
+
+xml-all:: $(foreach L,${LANGUAGES},xml-${L})
+
+distclean::
+	$(foreach L,${OTHERS},${RM} -r ${L})
+#########################################################################
+
+#########################################################################
+define	PO_template
+po/${1}.po:: ${XMLFILES-${PRI_LANG}} po/${DOCBASE}.pot
+	[ -d po ] || (echo ADD po/ TO CVS >&2; exit 1)
+	if [ ! -f $$@ ]; then						\
+		cp po/${DOCBASE}.pot $$@;				\
+	else								\
+		cp $$@ $$@.bank;					\
+		${MSGMERGE} -o $$@ $$@.bank po/${DOCBASE}.pot;		\
+	fi
+
+.PHONY:	po-${1}
+po-${1}:: po/${1}.po
+endef
+
+$(foreach L,${OTHERS},$(eval $(call PO_template,${L})))
+
+.PHONY:	po
+
+po::	$(foreach L,${OTHERS},po-${L})
 #########################################################################
-# Target "po" produces ".po" files from the manifested XML files for
-# the current language.
-POFILES	=${LANG}/${DOCBASE}-${LANG}.po ${XMLEXTRAFILES-${LANG}:.xml=.po}
-po::	${POFILES}
+
 #########################################################################
 #
 showvars::
 	@echo "DOCBASE=\"$(DOCBASE)\""
-	@echo "LANGUAGES=\"$(LANGUAGES)\""
+	@echo "PRI_LANG=\"$(PRI_LANG)\""
+	@echo "OTHERS=\"$(OTHERS)\""
 #
 #########################################################################
+
+#########################################################################
 # Show differences between two file revisions. To use this tool:
 # 	$ make OLD=old.xml NEW=new.xml diff
 # The ${DIFFS} macro can select a different output format:
@@ -244,26 +375,38 @@ diff::
 	xmldiff ${DIFFS} ${OLD} ${NEW}
 #
 #########################################################################
-# The "fdp-info-${LANG}.xml" file contains the <articleinfo> or 
+
+#########################################################################
+# The "${LANG}/fdp-info.xml" file contains the <articleinfo> or 
 # <bookinfo> stanza.  It is automatically generated from data in the
 # "rpm-info.xml" file whenever that file changes.
 #
 define fdp-info_template
-$(1)/fdp-info-$(1).xml::	$(RPMINFO)
+$(1)/fdp-info.xml::	$(RPMINFO)
 	${XSLTPROC} --stringparam lang $(1)				\
 		--stringparam fdpdir $(FDPDIR)				\
 		--stringparam doctype $(shell				\
-			doctype $(1)/$(DOCBASE)-$(1).xml		\
+			doctype ${PRI_LANG}/$(DOCBASE).xml		\
 		) ${FDPDIR}/docs-common/packaging/bookinfo.xsl 		\
 		$(RPMINFO) 					| 	\
-	$(XMLFORMAT) $(XMLFOPTS) > $(1)/fdp-info-$(1).xml.tmp	&&	\
-	move-if-change $(1)/fdp-info-$(1).xml.tmp $(1)/fdp-info-$(1).xml
+	$(XMLFORMAT) $(XMLFOPTS) >$$@
+
+clean::
+	${RM} ${1}/fdp-info.xml
 endef
+
+$(foreach L,${LANGUAGES},$(eval $(call fdp-info_template,${L})))
+
+.PHONY:	fdp-info
+
+fdp-info::  $(foreach LANG,${LANGUAGES},$(LANG)/fdp-info.xml)
 #
-$(foreach LANG,${LANGUAGES},$(eval $(call fdp-info_template,${LANG})))
-#
-fdp-info::  $(foreach LANG,${LANGUAGES},$(LANG)/fdp-info-$(LANG).xml)
-#
+#########################################################################
+
+#########################################################################
+# Stuff after here is for RPM packaging
+#########################################################################
+
 #########################################################################
 # Make a new changelog entry for an existing rpm-info.xml file.
 
@@ -279,11 +422,20 @@ colophon:: $(RPMINFO)
 	insert-colophon $(RPMINFO).tmp && 	\
 		move-if-change $(RPMINFO).tmp $(RPMINFO)
 
-#
-#########################################################################
-# End of Makefile.common
+
 #########################################################################
+.PHONY:	${DOCBASE}-${1}-distclean
+
+define	DISTCLEAN_template
+${DOCBASE}-$(1)-distclean::
+	${RM} *-$(1).omf
+	${RM} *-$(1).desktop
+endef
 
+$(foreach L,${LANGUAGES},$(eval $(call DISTCLEAN_template,${L})))
+
+distclean:: $(foreach L,${LANGUAGES},${DOCBASE}-${L}-distclean)
+#########################################################################
 
 clean::
 	${RM} $(DOCBASE)-$(VERSION)*.src.tar.gz
@@ -413,6 +565,9 @@ showvars::
 	@echo "PWD=$(PWD)"
 
 
+#########################################################################
+# End of Makefile.common
+#########################################################################
 # Local variables:
 # mode: makefile
 # End:
diff --git a/bin/fdp-functions b/bin/fdp-functions
index 285fff4..ed3d4a2 100644
--- a/bin/fdp-functions
+++ b/bin/fdp-functions
@@ -19,7 +19,7 @@ esac
 FDPBINDIR="${FDPDIR}/docs-common/bin"
 FDPPKGDIR="${FDPDIR}/docs-common/packaging"
 PRI_LANG=${PRI_LANG:-"en"}
-RPMINFO=${RPMINFO:-"${PRI_LANG}/rpm-info-${PRI_LANG}.xml"}
+RPMINFO=${RPMINFO:-"rpm-info.xml"}
 XSLTPROC=${XSLTPROC:-xsltproc}
 XMLFORMAT=${XMLFORMAT:-"${FDPBINDIR}/xmlformat"}
 XMLFOPTS=${XMLFOPTS:-"-f ${FDPBINDIR}/xmlformat-fdp.conf"}