docs/build: Avoid using multi-target pattern rules

Multi-target non-pattern rules and Multi-target pattern rules behave rather
differently.  From `Pattern Intro':

  Pattern rules may have more than one target.  Unlike normal rules, this does
  not act as many different rules with the same prerequisites and commands.
  If a pattern rule has multiple targets, `make' knows that the rule's
  commands are responsible for making all of the targets.  The commands are
  executed only once to make all the targets.

The intended use of the multi-target pattern rules was to avoid repeating the
identical recipe multiple times.  The issue can be demonstrated with the
generation of documentation from pandoc source.

  ./xen.git$ touch docs/features/template.pandoc
  ./xen.git$ make -C docs/
  # Regenerates html/features/template.html
  ./xen.git$ make -C docs/
  # Regenerates txt/features/template.txt
  ./xen.git$ make -C docs/
  # Regenerates pdf/features/template.pdf

To work around this, there need to be three distinct rules, so the execution
of one recipe doesn't short ciruit the others.  To avoid copy&paste
duplication, introduce a metarule, and evalute it for each document target.

As $(PANDOC) is used to generate documentation from different source types,
the metarule can be extended to also encompas the rule to create pdfs from
markdown.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Release-acked-by: Wei Liu <wei.liu2@citrix.com>

docs/Makefile

@@ -180,21 +180,23 @@ txt/%.txt: %.markdown
 	@$(INSTALL_DIR) $(@D)
 	$(INSTALL_DATA) $< $@
 
-pdf/%.pdf: %.markdown
+# Metarule for generating pandoc rules.
+define GENERATE_PANDOC_RULE
+# $(1) is the target documentation format. $(2) is the source format.
+
+$(1)/%.$(1): %.$(2)
 ifneq ($(PANDOC),)
-	@$(INSTALL_DIR) $(@D)
-	$(PANDOC) --number-sections --toc --standalone $< --output $@
+	@$(INSTALL_DIR) $$(@D)
+	$(PANDOC) --number-sections --toc --standalone $$< --output $$@
 else
-	@echo "pandoc not installed; skipping $@"
+	@echo "pandoc not installed; skipping $$@"
 endif
 
-pdf/%.pdf txt/%.txt html/%.html: %.pandoc
-ifneq ($(PANDOC),)
-	@$(INSTALL_DIR) $(@D)
-	$(PANDOC) --number-sections --toc --standalone $< --output $@
-else
-	@echo "pandoc not installed; skipping $@"
-endif
+endef
+$(eval $(call GENERATE_PANDOC_RULE,pdf,pandoc))   # pdf/%.pdf: %.pandoc
+$(eval $(call GENERATE_PANDOC_RULE,txt,pandoc))   # txt/%.txt: %.pandoc
+$(eval $(call GENERATE_PANDOC_RULE,html,pandoc))  # html/%.html: %.pandoc
+$(eval $(call GENERATE_PANDOC_RULE,pdf,markdown)) # pdf/%.pdf: %.markdown
 
 ifeq (,$(findstring clean,$(MAKECMDGOALS)))
 $(XEN_ROOT)/config/Docs.mk: