From 686b75bc254ee5800cd29aebadac5d058995d5a2 Mon Sep 17 00:00:00 2001 From: Tommy Reynolds Date: Wed, 15 Feb 2006 07:04:31 +0000 Subject: 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". --- Makefile.common | 297 +++++++++++++++++++++++++++++++++++++++++------------- bin/fdp-functions | 2 +- 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 @@ -13,16 +13,28 @@ # distclean -- See "clean" # ${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. @@ -30,6 +42,8 @@ # docs-common. Even if this file is present, defining FTPDIR via the # command line will take precedence. sinclude Make.paths +######################################################################### + ######################################################################### # Supply default values for the boilerplate files _unless_ the user has # provided their own values. @@ -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" \ @@ -101,11 +129,25 @@ SPECFILE=fedora-doc-$(DOCBASE).spec 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}) @@ -122,6 +167,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 @@ -135,38 +186,60 @@ ${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. @@ -174,62 +247,120 @@ html-nochunks:: $(foreach LANG,${LANGUAGES},html-nochunks-$(LANG)) 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 @@ -244,26 +375,38 @@ diff:: xmldiff ${DIFFS} ${OLD} ${NEW} # ######################################################################### -# The "fdp-info-${LANG}.xml" file contains the or + +######################################################################### +# The "${LANG}/fdp-info.xml" file contains the or # 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"} -- cgit