Fix the 'help' target to more succinctly and clearly indicate the

targets without spewing unnecessarily.  Add 'help-verbose' target to
produce a full list for people who want it.  Clean up duplicates and
use a better format to indicate locale-sensing targets.

1 files changed, 67 insertions, 82 deletions

diff --git a/Makefile.common b/Makefile.common
index c23129e..f8b1a6b 100644
--- a/Makefile.common
+++ b/Makefile.common
@@ -204,6 +204,7 @@ $(foreach L, ${LANGUAGES}, $(eval XMLDEPFILES-${L}+=${L}/${FDP_ENTITIES}))
 
 #########################################################################
 TFMT="%-31s -- %s\n"
+TPOFMT="%-30s* -- %s\n"
 #########################################################################
 
 #########################################################################
@@ -225,34 +226,16 @@ all::	html html-nochunks tarball # pdf
 
 help::
 	@echo -e 'The following targets are available for use with the make(1)'
-	@echo -e 'command. To make a target for a specific locale only, append'
-	@echo -e 'the suffix "-xy" to the target name, as in "make html-ja".\n'
-	@printf ${TFMT} 'fdp-info' 'Produces all $${LANG}/fdp-info.xml'
-	@printf ${TFMT} 'all'	'Builds html, html-nochunks, and tarball'
-	@printf ${TFMT} 'html'	'Renders XML into chunked HTML'
-	@printf ${TFMT} 'html-nochunks'	'Renders XML into one big HTML file'
-	@printf ${TFMT} 'pdf'	'Renders XML into one PDF file'
-	@printf ${TFMT} 'po'	'Updates .PO files for all $${OTHERS} locales'
-	@printf ${TFMT} 'text' 'Same as "txt" target'
-	@printf ${TFMT} 'txt' 'Renders XML into ASCII text file'
-
-	@echo -e 'The following targets are not locale specific.  Do not use a'
-	@echo -e 'locale suffix with these targets.\n'
-	@printf ${TFMT} 'help' 'This help; try "make help|sort"'
-	@printf ${TFMT} 'src-tarball' 'FIXME'
-	@printf ${TFMT} 'package-post' 'FIXME'
-	@printf ${TFMT} 'package-prep' 'FIXME'
-	@printf ${TFMT} 'srpm' 'FIXME'
-	@printf ${TFMT} 'noarch' 'FIXME'
-	@printf ${TFMT} 'rpm-common' 'FIXME'
-	@printf ${TFMT} 'rpm' 'Builds RPM packages'
-	@printf ${TFMT} 'tarball' 'Packages HTML files into tar(1) archive'
-	@printf ${TFMT} 'clean'	'Removes temporary files'
-	@printf ${TFMT} 'distclean' 'Removes product files and temporaries'
-	@printf ${TFMT} 'showvars'	'Displays convenient make(1) variables'
-
-	@echo -e '\nTo see a fully parsed list of locale-specific targets,'
-	@echo -e 'use the "make help-verbose" command.'
+	@echo -e 'command. Targets with a * marker can be built for a specific'
+	@echo -e 'locale only. To do this, append a locale suffix to the'
+	@echo -e 'target name, as in "make html-ja".'
+	@echo -e 'Valid locales are: ${OTHERS}'
+	@printf ${TPOFMT} 'all'	'Builds html, html-nochunks, and tarball'
+	@printf ${TFMT} 'help' 'Brief list of targets'
+	@printf ${TFMT} 'help-verbose' 'Full list, try "make help-verbose|sort"'
+
+
+help-verbose:: help
 
 ${TARGETS}::
 
@@ -267,6 +250,9 @@ showvars::
 	@echo "XMLDEPFILES=\"${XMLDEPFILES-${PRI_LANG}}\""
 	@echo "FDPCOMMONDIR=\"${FDPCOMMONDIR}\""
 
+help::
+	@printf ${TFMT} 'showvars' 'Displays convenient make(1) variables'
+
 #########################################################################
 # Obtain the document version and release info for building RPM's
 SPECFILE := $(firstword $(wildcard *.spec))
@@ -354,14 +340,14 @@ clean::
 
 ${1}/${DOC_ENTITIES}.ent::  ${1}/${DOC_ENTITIES}.xml
 
-help::
+help-verbose::
 	@printf ${TFMT} '${1}/${DOC_ENTITIES}.ent' 'Per-doc entities for locale "${1}"'
 	@printf ${TFMT} '${1}/${DOC_ENTITIES}.xml' 'Translated per-doc entities for locale "${1}"'
 endef
 
 ifneq	"${DOC_ENTITIES}" ""
 ${PRI_LANG}/${DOC_ENTITIES}.ent::  ${PRI_LANG}/${DOC_ENTITIES}.xml
-help::
+help-verbose::
 	@printf ${TFMT} '${PRI_LANG}/${DOC_ENTITIES}.ent' 'Per-doc entities for locale "${PRI_LANG}"'
 $(foreach L, ${OTHERS},$(eval $(call DOC_ENTITIES_template,${L})))
 
@@ -378,7 +364,7 @@ po/${POTBASE}.pot:: ${DOC_ENTITIES_XML-${PRI_LANG}} 			\
 		${PRI_LANG}/${FDP_ENTITIES} ${XMLFILES-${PRI_LANG}}
 	[ -d po/CVS ] || (echo ADD po/ TO CVS >&2; exit 1)
 	${XML2PO} ${XML2POFLAGS} -o $@ ${XMLFILES-${PRI_LANG}} ${DOC_ENTITIES_XML-${PRI_LANG}}
-help::
+help-verbose::
 	@printf ${TFMT} 'po/${POTBASE}.pot' 'Writes one POT file for all XML'
 
 showvars::
@@ -387,7 +373,8 @@ showvars::
 .PHONY:	pot
 pot::	po/${POTBASE}.pot
 help::
-	@printf ${TFMT} 'po' 'Writes one ${PRI_LANG} PO file for all XML'
+	@printf ${TPOFMT} 'po' 'Writes one ${PRI_LANG} PO file for all XML'
+	@printf ${TFMT} 'pot' 'Writes one POT file for all XML'
 #########################################################################
 
 #########################################################################
@@ -410,8 +397,7 @@ postat-${1}::
 	@echo "${1}: $(shell $(MSGFMT) --stat po/${1}.po 2>&1 | \
 		sed 's@[^0-9]\+@/@g')"
 
-help::
-	@printf ${TFMT} 'po-${1}' 'Creates or updates locale ${1} .PO file'
+help-verbose::
 	@printf ${TFMT} 'po/${1}.po' 'Creates or updates locale ${1} .PO file'
 
 endef
@@ -456,26 +442,21 @@ xml-${1}::	${XMLDEPFILES-${1}} ${XMLFILES-${1}}
 distclean::
 	${RM} -r ${1}
 
-help::
+help-verbose::
 	@printf ${TFMT} 'xml-${1}' 'Produces translated XML for locale ${1}'
 
 endef
 
 .PHONY:	xml-${PRI_LANG}
-
 xml-${PRI_LANG}:: ${XMLFILES-${PRI_LANG}}
 
-help::
-	@printf ${TFMT} 'xml-${PRI_LANG}' 'Comfirms primary language XML files.'
-
 $(foreach L,${OTHERS},$(eval $(call XMLTARGET_template,${L})))
 
-.PHONY:	xml-all
-
-xml-all:: $(foreach L,${LANGUAGES},xml-${L})
+.PHONY:	xml xml-all
+xml xml-all:: $(foreach L,${LANGUAGES},xml-${L})
 
 help::
-	@printf ${TFMT} 'xml-all' 'Creates all XML locale files'
+	@printf ${TPOFMT} 'xml' 'Creates all XML locale files, no validation'
 
 distclean::
 	$(foreach L,${OTHERS},${RM} -r ${L})
@@ -539,9 +520,6 @@ $(foreach F,${OMFINFILES},$(eval $(call XML_template,${1},${PRI_LANG}/${F})))
 clean::
 	${RM} ${OMFINFILES-${1}}
 
-help::
-	@printf ${TFMT} 'omf-in-${1}' 'Make OMF input file for ${1}'
-
 endef
 
 $(foreach L,${OTHERS},$(eval $(call OMFIN_template,${L})))
@@ -550,7 +528,7 @@ $(foreach L,${OTHERS},$(eval $(call OMFIN_template,${L})))
 omf-in:: $(foreach L,${LANGUAGES},${OMFINFILES-${L}})
 
 help::
-	@printf ${TFMT} 'omf-in' 'Make all OMF input files'
+	@printf ${TPOFMT} 'omf-in' 'Make all OMF input files'
 
 
 # To make the real OMF, just do a quick bit of sed processing.
@@ -577,9 +555,6 @@ omf-${1}:: ${OMFFILES-${1}}
 clean::
 	${RM} ${OMFFILES-${1}}
 
-help::
-	@printf ${TFMT} 'omf-${1}' 'Make all OMF files for ${1} locale'
-
 endef
 
 $(foreach L,${LANGUAGES},$(eval $(call OMF_template,${L})))
@@ -587,7 +562,7 @@ $(foreach L,${LANGUAGES},$(eval $(call OMF_template,${L})))
 .PHONY: omf
 omf:: $(foreach L,${LANGUAGES},${OMFFILES-${L}})
 help::
-	@printf ${TFMT} 'omf' 'Make all OMF files for all locales'
+	@printf ${TPOFMT} 'omf' 'Make all OMF files for all locales'
 # End of OMF ###############################
 
 #########################################################################
@@ -622,8 +597,7 @@ endif
 distclean::
 	${RM} -r ${DOCBASE}-${1}
 
-help::
-	@printf ${TFMT} 'html-${1}' 'Renders XML into locale ${1}'
+help-verbose::
 	@printf ${TFMT} '${1}/index.html' 'Renders XML into locale ${1}'
 endef
 
@@ -632,6 +606,9 @@ $(foreach L,${LANGUAGES},$(eval $(call HTML_template,${L})))
 .PHONY:	html
 
 html::	$(foreach L,${LANGUAGES},html-${L})
+
+help::
+	@printf ${TPOFMT} 'html' 'Renders XML into chunked HTML'
 #
 #########################################################################
 
@@ -659,8 +636,7 @@ distclean::
 	${RM} fedora.css
 	${RM} watermark.png
 
-help::
-	@printf ${TFMT} 'html-nochunks-${1}' 'Renders XML into locale ${1} HTML'
+help-verbose::
 	@printf ${TFMT} '${DOCBASE}-${1}.html' 'Renders XML into locale ${1} HTML'
 endef
 
@@ -669,6 +645,9 @@ $(foreach L,${LANGUAGES},$(eval $(call HTMLNOCHUNK_template,${L})))
 .PHONY:	html-nochunks
 
 html-nochunks::	$(foreach L,${LANGUAGES},html-nochunks-$(L))
+
+help::
+	@printf ${TPOFMT} 'html-nochunks' 'Renders XML into locale ${1} HTML'
 #
 #########################################################################
 
@@ -677,13 +656,16 @@ html-nochunks::	$(foreach L,${LANGUAGES},html-nochunks-$(L))
 # image files.  Any ".eps" files are ignored.
 #
 define	HTMLTAR_template
+.PHONY: tarball-${1}
+tarball-${1}:: ${DOCBASE}-${1}.tar.gz
+
 ${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
 
-help::
+help-verbose::
 	@printf ${TFMT} '${DOCBASE}-${1}.tar.gz' 'Tar archive of HTML and images'
 endef
 
@@ -692,6 +674,9 @@ $(foreach L,${LANGUAGES},$(eval $(call HTMLTAR_template,${L})))
 .PHONY:	tarball
 
 tarball::	$(foreach LANG,${LANGUAGES},$(DOCBASE)-$(LANG).tar.gz)
+
+help::
+	@printf ${TPOFMT} 'tarball' 'Tar archive of HTML and images'
 #
 #########################################################################
 
@@ -709,8 +694,7 @@ ${1}/${DOCBASE}.fo:: ${XMLFILES-${1}} ${XMLDEPFILES-${1}}
 	     ${XSLPDF} ${1}/${DOCBASE}.xml | ${XMLLINT} --format -o $$@ -
 clean::
 	${RM} ${1}/${DOCBASE}.fo
-help::
-	@printf ${TFMT} 'fo-${1}' 'Creates ${1}/${DOCBASE}.fo file'
+help-verbose::
 	@printf ${TFMT} '${1}/${DOCBASE}.fo' 'XSL-FO file for locale ${1}'
 endef
 
@@ -719,8 +703,7 @@ $(foreach L,${LANGUAGES},$(eval $(call FO_template,${L})))
 .PHONY:	fo fo-all
 fo fo-all::	$(foreach L,${LANGUAGES},fo-${L})
 help::
-	@printf ${TFMT} 'fo' 'Generate .FO files for all languages'
-	@printf ${TFMT} 'fo-all' 'Generate .FO files for all languages'
+	@printf ${TPOFMT} 'fo' 'Generate .FO files for all languages'
 
 define	PDF_template
 .PHONY:	pdf-${1}
@@ -733,9 +716,8 @@ ${DOCBASE}-${1}.pdf:: ${1}/${DOCBASE}.fo
 distclean::
 	${RM} ${DOCBASE}-${1}.pdf
 
-help::
-	@printf ${TFMT} 'pdf-${1}' 'Renders XML-FO into PDF for locale ${1}'
-	@printf ${TFMT} '${DOCBASE}-${1}.pdf' 'Renders XML-FO into PDF file'
+help-verbose::
+	@printf ${TFMT} '${DOCBASE}-${1}.pdf' 'Renders XML-FO into PDF file for locale ${1}'
 
 endef
 
@@ -745,6 +727,9 @@ $(foreach L,${LANGUAGES},$(eval $(call PDF_template,${L})))
 
 pdf::	$(foreach LANG,${LANGUAGES},pdf-$(LANG))
 
+help::
+	@printf ${TPOFMT} 'pdf' 'Renders XML-FO into PDF file'
+
 
 define  TXT_template
 .PHONY: txt-${1} text-${1}
@@ -767,9 +752,7 @@ clean::
 distclean::
 	${RM} ${DOCBASE}-${1}.txt
 
-help::
-	@printf ${TFMT} 'txt-${1}' 'Renders XML into ASCII text for locale ${1}'
-	@printf ${TFMT} 'text-${1}' 'Renders XML into ASCII text for locale ${1}'
+help-verbose::
 	@printf ${TFMT} '${DOCBASE}-${1}.txt' 'Renders XML into ASCII text for locale ${1}'
 
 endef
@@ -779,6 +762,10 @@ $(foreach L,${LANGUAGES},$(eval $(call TXT_template,${L})))
 .PHONY: txt text
 
 txt text::	$(foreach LANG,${LANGUAGES},txt-$(LANG))
+
+help::
+	@printf ${TPOFMT} 'txt' 'Renders XML into ASCII text'
+	@printf ${TPOFMT} 'text' 'Renders XML into ASCII text'
 #
 #########################################################################
 
@@ -829,7 +816,7 @@ ${1}/${RPMINFO}::  po/${1}.po ${PRI_LANG}/${RPMINFO}
 clean::
 	${RM} ${1}/${RPMINFO}
 
-help::
+help-verbose::
 	@printf ${TFMT} '${1}/${RPMINFO}' 'Make translated document revision info'
 endef
 
@@ -859,7 +846,7 @@ $(1)/fdp-info.xml::	${1}/$(RPMINFO)
 clean::
 	${RM} ${1}/fdp-info.xml
 
-help::
+help-verbose::
 	@printf ${TFMT} '${1}/fdp-info.xml' 'Locale ${1} packaging information'
 
 endef
@@ -871,7 +858,7 @@ $(foreach L,${LANGUAGES},$(eval $(call fdp-info_template,${L})))
 fdp-info::  $(foreach LANG,${LANGUAGES},$(LANG)/fdp-info.xml)
 
 help::
-	@printf ${TFMT} 'fdp-info' 'Outputs all locale-specific packaging info'
+	@printf ${TPOFMT} 'fdp-info' 'Outputs XML document info'
 
 define khelp_template
 .PHONY: khelp-$(1)
@@ -888,8 +875,6 @@ khelp-$(1):: ${XMLFILES-$(1)} ${XMLDEPFILES-$(1)}
 clean::
 	${RM} -rf kde-$(1)
 
-help::
-	@printf ${TFMT} 'khelp-$(1)' 'Build khelpcenter files for locale $(1)'
 endef
 
 $(foreach L,${LANGUAGES},$(eval $(call khelp_template,${L})))
@@ -899,7 +884,7 @@ $(foreach L,${LANGUAGES},$(eval $(call khelp_template,${L})))
 khelp:: $(foreach LANG,${LANGUAGES},khelp-$(LANG))
 
 help::
-	@printf ${TFMT} 'khelp' 'Build all locale-specific khelpcenter files'
+	@printf ${TPOFMT} 'khelp' 'Build all locale-specific khelpcenter files'
 #
 #########################################################################
 
@@ -933,21 +918,23 @@ help::
 #	@printf ${TFMT} 'colophon' 'Adds colophon entry to rpm-info.xml file'
 
 #########################################################################
-.PHONY:	${DOCBASE}-${1}-distclean
+.PHONY:	distclean-${1} ${DOCBASE}-${1}-distclean
 
 define	DISTCLEAN_template
-${DOCBASE}-$(1)-distclean::
+distclean-${1} ${DOCBASE}-$(1)-distclean::
 	${RM} *-$(1).omf
 	${RM} *-$(1).desktop
 
-help::
-	@printf ${TFMT} '${DOCBASE}-${1}-distclean' 'Removes locale ${1} product files'
-
 endef
 
 $(foreach L,${LANGUAGES},$(eval $(call DISTCLEAN_template,${L})))
 
 distclean:: $(foreach L,${LANGUAGES},${DOCBASE}-${L}-distclean)
+help::
+	@printf ${TPOFMT} 'distclean' 'Removes product files and temporary files'
+	@printf ${TFMT} 'clean' 'Removes temporary files'
+#########################################################################
+
 #########################################################################
 
 clean::
@@ -978,7 +965,7 @@ ${1}/$${FDP_ENTITIES}::
 clean::
 	${RM} ${1}/$${FDP_ENTITIES}
 
-help::
+help-verbose::
 	@printf ${TFMT} '${1}/$${FDP_ENTITIES}' 'Link locale ${1} to FDP entities'
 endef
 
@@ -998,7 +985,7 @@ set-locale-${1}:: ${XMLDEPFILES-${1}}
 clean::
 	${RM} ${XMLDEPFILES-${1}}
 
-help::
+help-verbose::
 	@printf ${TFMT} 'set-locale-${1}' 'Link to locale ${1} FDP entities'
 endef
 
@@ -1017,8 +1004,6 @@ define	VALIDATE_template
 validate-xml-${1}:: ${XMLFILES-${1}} ${XMLDEPFILES-${1}}
 	${XMLLINT} --noout --xinclude --postvalid ${1}/${DOCBASE}.xml
 
-help::
-	@printf ${TFMT} 'validate-xml-${1}' 'Validate locale "${1}" XML'
 endef
 
 $(foreach L,${PRI_LANG} ${OTHERS},$(eval $(call VALIDATE_template,${L})))
@@ -1028,7 +1013,7 @@ $(foreach L,${PRI_LANG} ${OTHERS},$(eval $(call VALIDATE_template,${L})))
 validate-xml: $(foreach L,${PRI_LANG} ${OTHERS},validate-xml-${L})
 
 help::
-	@printf ${TFMT} 'validate-xml' 'Validate all XML'
+	@printf ${TPOFMT} 'validate-xml' 'Validate all XML'
 #
 #########################################################################