[PATCH 0/7] docs/build fixes

[PATCH 0/7] docs/build fixes

[Andrew Cooper]

This is the results of shaving a yak which started while introducing a pandoc
document in the Migration v2 libxc series

Andrew Cooper (7):
  docs/build: Misc cleanup
  docs/build: Do not open-code $*
  docs/build: Move two rules for consistency, and comment sections
  docs/build: Do not use move-if-changed
  docs/build: Do not create directories if we are not going to use them
  docs/build: Move install checks into individual build targets
  docs/build: Support generation of pandoc documents

 docs/Makefile |  123 +++++++++++++++++++++++++++++----------------------------
 1 file changed, 63 insertions(+), 60 deletions(-)

-- 
1.7.10.4

[PATCH 1/7] docs/build: Misc cleanup

[Andrew Cooper]

 * Use $(PANDOC) from ./configure
 * Swap '-N' for its less-obscure longer form
 * Don't explicitly echo about markdown.  The call to markdown is emitted
 * Whitespace cleanup

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
CC: Ian Campbell <Ian.Campbell@citrix.com>
CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
CC: Wei Liu <wei.liu2@citrix.com>
---
 docs/Makefile |    5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index 854fb50..f4c8412 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -84,7 +84,7 @@ man5/%.5: man/%.pod.5 Makefile
 .PHONY: clean
 clean:
 	$(MAKE) -C figs clean
-	rm -rf .word_count *.aux *.dvi *.bbl *.blg *.glo *.idx *~ 
+	rm -rf .word_count *.aux *.dvi *.bbl *.blg *.glo *.idx *~
 	rm -rf *.ilg *.log *.ind *.toc *.bak *.tmp core
 	rm -rf html txt pdf
 	rm -rf man5
@@ -115,7 +115,6 @@ html/index.html: $(DOC_HTML) $(CURDIR)/gen-html-index INDEX
 html/%.html: %.markdown
 	$(INSTALL_DIR) $(@D)
 ifdef MARKDOWN
-	@echo "Running markdown to generate $*.html ... "
 	$(MARKDOWN) $< > $@.tmp ; \
 	$(call move-if-changed,$@.tmp,$@)
 else
@@ -189,7 +188,7 @@ endif
 
 pdf/%.pdf: %.markdown
 	$(INSTALL_DIR) $(@D)
-	pandoc -N --toc --standalone $< --output $@
+	$(PANDOC) --number-sections --toc --standalone $< --output $@
 
 ifeq (,$(findstring clean,$(MAKECMDGOALS)))
 $(XEN_ROOT)/config/Docs.mk:
-- 
1.7.10.4

[PATCH 2/7] docs/build: Do not open-code $*

[Andrew Cooper]

Sometimes there is already a round enough wheel to hand.

No functional change.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
CC: Ian Campbell <Ian.Campbell@citrix.com>
CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
CC: Wei Liu <wei.liu2@citrix.com>
---
 docs/Makefile |    6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index f4c8412..6f79584 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -73,13 +73,11 @@ endif
 
 man1/%.1: man/%.pod.1 Makefile
 	$(INSTALL_DIR) $(@D)
-	$(POD2MAN) --release=$(VERSION) --name=`echo $@ | sed 's/^man1.//'| \
-		sed 's/.1//'` -s 1 -c "Xen" $< $@
+	$(POD2MAN) --release=$(VERSION) --name=$* -s 1 -c "Xen" $< $@
 
 man5/%.5: man/%.pod.5 Makefile
 	$(INSTALL_DIR) $(@D)
-	$(POD2MAN) --release=$(VERSION) --name=`echo $@ | sed 's/^man5.//'| \
-		sed 's/.5//'` -s 5 -c "Xen" $< $@
+	$(POD2MAN) --release=$(VERSION) --name=$* -s 5 -c "Xen" $< $@
 
 .PHONY: clean
 clean:
-- 
1.7.10.4

[PATCH 3/7] docs/build: Move two rules for consistency, and comment sections

[Andrew Cooper]

No functional change.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
CC: Ian Campbell <Ian.Campbell@citrix.com>
CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
CC: Wei Liu <wei.liu2@citrix.com>
---
 docs/Makefile |   21 ++++++++++++---------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index 6f79584..0b458f1 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -16,7 +16,7 @@ MARKDOWNSRC-y := $(sort $(wildcard misc/*.markdown))
 
 TXTSRC-y := $(sort $(wildcard misc/*.txt))
 
-
+# Documentation targets
 DOC_MAN1 := $(patsubst man/%.pod.1,man1/%.1,$(MAN1SRC-y))
 DOC_MAN5 := $(patsubst man/%.pod.5,man5/%.5,$(MAN5SRC-y))
 DOC_HTML := $(patsubst %.markdown,html/%.html,$(MARKDOWNSRC-y)) \
@@ -30,6 +30,7 @@ DOC_TXT  := $(patsubst %.txt,txt/%.txt,$(TXTSRC-y)) \
             $(patsubst man/%.pod.5,txt/man/%.5.txt,$(MAN5SRC-y))
 DOC_PDF  := $(patsubst %.markdown,pdf/%.pdf,$(MARKDOWNSRC-y))
 
+# Top level build targets
 .PHONY: all
 all: build
 
@@ -71,14 +72,6 @@ else
 	@echo "pandoc not installed; skipping pdfs."
 endif
 
-man1/%.1: man/%.pod.1 Makefile
-	$(INSTALL_DIR) $(@D)
-	$(POD2MAN) --release=$(VERSION) --name=$* -s 1 -c "Xen" $< $@
-
-man5/%.5: man/%.pod.5 Makefile
-	$(INSTALL_DIR) $(@D)
-	$(POD2MAN) --release=$(VERSION) --name=$* -s 5 -c "Xen" $< $@
-
 .PHONY: clean
 clean:
 	$(MAKE) -C figs clean
@@ -93,6 +86,7 @@ distclean: clean
 	rm -rf $(XEN_ROOT)/config/Docs.mk config.log config.status config.cache \
 		autom4te.cache
 
+# Top level install targets
 .PHONY: install-man-pages
 install-man-pages: man-pages
 	$(INSTALL_DIR) $(DESTDIR)$(MANDIR)
@@ -107,6 +101,15 @@ install-html: html txt figs
 .PHONY: install
 install: install-man-pages install-html
 
+# Individual file build targets
+man1/%.1: man/%.pod.1 Makefile
+	$(INSTALL_DIR) $(@D)
+	$(POD2MAN) --release=$(VERSION) --name=$* -s 1 -c "Xen" $< $@
+
+man5/%.5: man/%.pod.5 Makefile
+	$(INSTALL_DIR) $(@D)
+	$(POD2MAN) --release=$(VERSION) --name=$* -s 5 -c "Xen" $< $@
+
 html/index.html: $(DOC_HTML) $(CURDIR)/gen-html-index INDEX
 	$(PERL) -w -- $(CURDIR)/gen-html-index -i INDEX html $(DOC_HTML)
 
-- 
1.7.10.4

[PATCH 4/7] docs/build: Do not use move-if-changed

[Andrew Cooper]

Nothing expensive depends on these results.

Also prefer $(INSTALL_DATA) over cp to get correct file attributes (see
fb33b2b "docs: make .txt files over-writable when building from r/o sources")

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
CC: Ian Campbell <Ian.Campbell@citrix.com>
CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
CC: Wei Liu <wei.liu2@citrix.com>
---
 docs/Makefile |   21 +++++++--------------
 1 file changed, 7 insertions(+), 14 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index 0b458f1..d31b36f 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -116,8 +116,7 @@ html/index.html: $(DOC_HTML) $(CURDIR)/gen-html-index INDEX
 html/%.html: %.markdown
 	$(INSTALL_DIR) $(@D)
 ifdef MARKDOWN
-	$(MARKDOWN) $< > $@.tmp ; \
-	$(call move-if-changed,$@.tmp,$@)
+	$(MARKDOWN) $< > $@
 else
 	@echo "markdown not installed; skipping $*.html."
 endif
@@ -129,8 +128,7 @@ html/%.txt: %.txt
 html/man/%.1.html: man/%.pod.1 Makefile
 	$(INSTALL_DIR) $(@D)
 ifdef POD2HTML
-	$(POD2HTML) --infile=$< --outfile=$@.tmp
-	$(call move-if-changed,$@.tmp,$@)
+	$(POD2HTML) --infile=$< --outfile=$@
 else
 	@echo "pod2html not installed; skipping $<."
 endif
@@ -138,8 +136,7 @@ endif
 html/man/%.5.html: man/%.pod.5 Makefile
 	$(INSTALL_DIR) $(@D)
 ifdef POD2HTML
-	$(POD2HTML) --infile=$< --outfile=$@.tmp
-	$(call move-if-changed,$@.tmp,$@)
+	$(POD2HTML) --infile=$< --outfile=$@
 else
 	@echo "pod2html not installed; skipping $<."
 endif
@@ -161,19 +158,16 @@ html/hypercall/%/index.html: $(CURDIR)/xen-headers Makefile
 
 txt/%.txt: %.txt
 	$(INSTALL_DIR) $(@D)
-	cp $< $@.tmp
-	$(call move-if-changed,$@.tmp,$@)
+	$(INSTALL_DATA) $< $@
 
 txt/%.txt: %.markdown
 	$(INSTALL_DIR) $(@D)
-	cp $< $@.tmp
-	$(call move-if-changed,$@.tmp,$@)
+	$(INSTALL_DATA) $< $@
 
 txt/man/%.1.txt: man/%.pod.1 Makefile
 	$(INSTALL_DIR) $(@D)
 ifdef POD2TEXT
-	$(POD2TEXT) $< $@.tmp
-	$(call move-if-changed,$@.tmp,$@)
+	$(POD2TEXT) $< $@
 else
 	@echo "pod2text not installed; skipping $<."
 endif
@@ -181,8 +175,7 @@ endif
 txt/man/%.5.txt: man/%.pod.5 Makefile
 	$(INSTALL_DIR) $(@D)
 ifdef POD2TEXT
-	$(POD2TEXT) $< $@.tmp
-	$(call move-if-changed,$@.tmp,$@)
+	$(POD2TEXT) $< $@
 else
 	@echo "pod2text not installed; skipping $<."
 endif
-- 
1.7.10.4

[PATCH 5/7] docs/build: Do not create directories if we are not going to use them

[Andrew Cooper]

and be quite about doing so; these are only intermediate directories.

No practical change, but the build log is roughly halved.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
CC: Ian Campbell <Ian.Campbell@citrix.com>
CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
CC: Wei Liu <wei.liu2@citrix.com>
---
 docs/Makefile |   22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index d31b36f..6de05e4 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -103,39 +103,39 @@ install: install-man-pages install-html
 
 # Individual file build targets
 man1/%.1: man/%.pod.1 Makefile
-	$(INSTALL_DIR) $(@D)
+	@$(INSTALL_DIR) $(@D)
 	$(POD2MAN) --release=$(VERSION) --name=$* -s 1 -c "Xen" $< $@
 
 man5/%.5: man/%.pod.5 Makefile
-	$(INSTALL_DIR) $(@D)
+	@$(INSTALL_DIR) $(@D)
 	$(POD2MAN) --release=$(VERSION) --name=$* -s 5 -c "Xen" $< $@
 
 html/index.html: $(DOC_HTML) $(CURDIR)/gen-html-index INDEX
 	$(PERL) -w -- $(CURDIR)/gen-html-index -i INDEX html $(DOC_HTML)
 
 html/%.html: %.markdown
-	$(INSTALL_DIR) $(@D)
 ifdef MARKDOWN
+	@$(INSTALL_DIR) $(@D)
 	$(MARKDOWN) $< > $@
 else
 	@echo "markdown not installed; skipping $*.html."
 endif
 
 html/%.txt: %.txt
-	$(INSTALL_DIR) $(@D)
+	@$(INSTALL_DIR) $(@D)
 	$(INSTALL_DATA) $< $@
 
 html/man/%.1.html: man/%.pod.1 Makefile
-	$(INSTALL_DIR) $(@D)
 ifdef POD2HTML
+	@$(INSTALL_DIR) $(@D)
 	$(POD2HTML) --infile=$< --outfile=$@
 else
 	@echo "pod2html not installed; skipping $<."
 endif
 
 html/man/%.5.html: man/%.pod.5 Makefile
-	$(INSTALL_DIR) $(@D)
 ifdef POD2HTML
+	@$(INSTALL_DIR) $(@D)
 	$(POD2HTML) --infile=$< --outfile=$@
 else
 	@echo "pod2html not installed; skipping $<."
@@ -157,31 +157,31 @@ html/hypercall/%/index.html: $(CURDIR)/xen-headers Makefile
 -include $(wildcard html/hypercall/*/.deps)
 
 txt/%.txt: %.txt
-	$(INSTALL_DIR) $(@D)
+	@$(INSTALL_DIR) $(@D)
 	$(INSTALL_DATA) $< $@
 
 txt/%.txt: %.markdown
-	$(INSTALL_DIR) $(@D)
+	@$(INSTALL_DIR) $(@D)
 	$(INSTALL_DATA) $< $@
 
 txt/man/%.1.txt: man/%.pod.1 Makefile
-	$(INSTALL_DIR) $(@D)
 ifdef POD2TEXT
+	@$(INSTALL_DIR) $(@D)
 	$(POD2TEXT) $< $@
 else
 	@echo "pod2text not installed; skipping $<."
 endif
 
 txt/man/%.5.txt: man/%.pod.5 Makefile
-	$(INSTALL_DIR) $(@D)
 ifdef POD2TEXT
+	@$(INSTALL_DIR) $(@D)
 	$(POD2TEXT) $< $@
 else
 	@echo "pod2text not installed; skipping $<."
 endif
 
 pdf/%.pdf: %.markdown
-	$(INSTALL_DIR) $(@D)
+	@$(INSTALL_DIR) $(@D)
 	$(PANDOC) --number-sections --toc --standalone $< --output $@
 
 ifeq (,$(findstring clean,$(MAKECMDGOALS)))
-- 
1.7.10.4

[PATCH 6/7] docs/build: Move install checks into individual build targets

[Andrew Cooper]

For top-level targets which use more than a single program to produce content
(txt already, pdf once pandoc is supported), these current checks are
unsuitable.

By moving the the install checks to the rules which actually use the programs,
it is now possible to build a subset of a top-level target depending on the
installed programs.

As a bonus, it removes the need to recurse for txt, man-pages and pdf targets.

A side effect of this is that every individual source which cannot be
generated will have a specific message logged, giving the file and program.
As such, these message are updated to consistently report the target file
which was not generated.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
CC: Ian Campbell <Ian.Campbell@citrix.com>
CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
CC: Wei Liu <wei.liu2@citrix.com>
---
 docs/Makefile |   43 ++++++++++++++++++++-----------------------
 1 file changed, 20 insertions(+), 23 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index 6de05e4..487f7a6 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -41,12 +41,7 @@ build: html txt pdf man-pages figs
 html: $(DOC_HTML) html/index.html
 
 .PHONY: txt
-txt:
-ifdef POD2TEXT
-	$(MAKE) $(DOC_TXT)
-else
-	@echo "pod2text not installed; skipping text outputs."
-endif
+txt: $(DOC_TXT)
 
 .PHONY: figs
 figs:
@@ -57,20 +52,10 @@ else
 endif
 
 .PHONY: man-pages
-man-pages:
-ifdef POD2MAN
-	$(MAKE) $(DOC_MAN1) $(DOC_MAN5)
-else
-	@echo "pod2man not installed; skipping man-pages."
-endif
+man-pages: $(DOC_MAN1) $(DOC_MAN5)
 
 .PHONY: pdf
-pdf:
-ifdef PANDOC
-	$(MAKE) $(DOC_PDF)
-else
-	@echo "pandoc not installed; skipping pdfs."
-endif
+pdf: $(DOC_PDF)
 
 .PHONY: clean
 clean:
@@ -103,12 +88,20 @@ install: install-man-pages install-html
 
 # Individual file build targets
 man1/%.1: man/%.pod.1 Makefile
+ifdef POD2MAN
 	@$(INSTALL_DIR) $(@D)
 	$(POD2MAN) --release=$(VERSION) --name=$* -s 1 -c "Xen" $< $@
+else
+	@echo "pod2man not installed; skipping $(@F)"
+endif
 
 man5/%.5: man/%.pod.5 Makefile
+ifdef POD2MAN
 	@$(INSTALL_DIR) $(@D)
 	$(POD2MAN) --release=$(VERSION) --name=$* -s 5 -c "Xen" $< $@
+else
+	@echo "pod2man not installed; skipping $(@F)"
+endif
 
 html/index.html: $(DOC_HTML) $(CURDIR)/gen-html-index INDEX
 	$(PERL) -w -- $(CURDIR)/gen-html-index -i INDEX html $(DOC_HTML)
@@ -118,7 +111,7 @@ ifdef MARKDOWN
 	@$(INSTALL_DIR) $(@D)
 	$(MARKDOWN) $< > $@
 else
-	@echo "markdown not installed; skipping $*.html."
+	@echo "markdown not installed; skipping $(@F)"
 endif
 
 html/%.txt: %.txt
@@ -130,7 +123,7 @@ ifdef POD2HTML
 	@$(INSTALL_DIR) $(@D)
 	$(POD2HTML) --infile=$< --outfile=$@
 else
-	@echo "pod2html not installed; skipping $<."
+	@echo "pod2html not installed; skipping $(@F)"
 endif
 
 html/man/%.5.html: man/%.pod.5 Makefile
@@ -138,7 +131,7 @@ ifdef POD2HTML
 	@$(INSTALL_DIR) $(@D)
 	$(POD2HTML) --infile=$< --outfile=$@
 else
-	@echo "pod2html not installed; skipping $<."
+	@echo "pod2html not installed; skipping $(@F)"
 endif
 
 # For non-x86 arches exclude the subarch whole x86 arch.
@@ -169,7 +162,7 @@ ifdef POD2TEXT
 	@$(INSTALL_DIR) $(@D)
 	$(POD2TEXT) $< $@
 else
-	@echo "pod2text not installed; skipping $<."
+	@echo "pod2text not installed; skipping $(@F)"
 endif
 
 txt/man/%.5.txt: man/%.pod.5 Makefile
@@ -177,12 +170,16 @@ ifdef POD2TEXT
 	@$(INSTALL_DIR) $(@D)
 	$(POD2TEXT) $< $@
 else
-	@echo "pod2text not installed; skipping $<."
+	@echo "pod2text not installed; skipping $(@F)"
 endif
 
 pdf/%.pdf: %.markdown
+ifdef PANDOC
 	@$(INSTALL_DIR) $(@D)
 	$(PANDOC) --number-sections --toc --standalone $< --output $@
+else
+	@echo "pandoc not installed; skipping $(@F)"
+endif
 
 ifeq (,$(findstring clean,$(MAKECMDGOALS)))
 $(XEN_ROOT)/config/Docs.mk:
-- 
1.7.10.4

[PATCH 7/7] docs/build: Support generation of pandoc documents

[Andrew Cooper]

pandoc is a superset of markdown

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
CC: Ian Campbell <Ian.Campbell@citrix.com>
CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
CC: Wei Liu <wei.liu2@citrix.com>
---
 docs/Makefile |   15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/docs/Makefile b/docs/Makefile
index 487f7a6..6266b32 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -16,19 +16,24 @@ MARKDOWNSRC-y := $(sort $(wildcard misc/*.markdown))
 
 TXTSRC-y := $(sort $(wildcard misc/*.txt))
 
+PANDOCSRC-y := $(sort $(wildcard specs/*.pandoc))
+
 # Documentation targets
 DOC_MAN1 := $(patsubst man/%.pod.1,man1/%.1,$(MAN1SRC-y))
 DOC_MAN5 := $(patsubst man/%.pod.5,man5/%.5,$(MAN5SRC-y))
 DOC_HTML := $(patsubst %.markdown,html/%.html,$(MARKDOWNSRC-y)) \
+            $(patsubst %.pandoc,html/%.html,$(PANDOCSRC-y)) \
             $(patsubst man/%.pod.1,html/man/%.1.html,$(MAN1SRC-y)) \
             $(patsubst man/%.pod.5,html/man/%.5.html,$(MAN5SRC-y)) \
             $(patsubst %.txt,html/%.txt,$(TXTSRC-y)) \
             $(patsubst %,html/hypercall/%/index.html,$(DOC_ARCHES))
 DOC_TXT  := $(patsubst %.txt,txt/%.txt,$(TXTSRC-y)) \
             $(patsubst %.markdown,txt/%.txt,$(MARKDOWNSRC-y)) \
+            $(patsubst %.pandoc,txt/%.txt,$(PANDOCSRC-y)) \
             $(patsubst man/%.pod.1,txt/man/%.1.txt,$(MAN1SRC-y)) \
             $(patsubst man/%.pod.5,txt/man/%.5.txt,$(MAN5SRC-y))
-DOC_PDF  := $(patsubst %.markdown,pdf/%.pdf,$(MARKDOWNSRC-y))
+DOC_PDF  := $(patsubst %.markdown,pdf/%.pdf,$(MARKDOWNSRC-y)) \
+            $(patsubst %.pandoc,pdf/%.pdf,$(PANDOCSRC-y))
 
 # Top level build targets
 .PHONY: all
@@ -181,6 +186,14 @@ else
 	@echo "pandoc not installed; skipping $(@F)"
 endif
 
+pdf/%.pdf txt/%.txt html/%.html: %.pandoc
+ifdef PANDOC
+	@$(INSTALL_DIR) $(@D)
+	$(PANDOC) --number-sections --toc --standalone $< --output $@
+else
+	@echo "pandoc not installed; skipping $(@F)"
+endif
+
 ifeq (,$(findstring clean,$(MAKECMDGOALS)))
 $(XEN_ROOT)/config/Docs.mk:
 	$(error You have to run ./configure before building docs)
-- 
1.7.10.4

Re: [PATCH 2/7] docs/build: Do not open-code $*

[Jan Beulich]

>>> On 20.04.15 at 12:49, <andrew.cooper3@citrix.com> wrote:
> --- a/docs/Makefile
> +++ b/docs/Makefile
> @@ -73,13 +73,11 @@ endif
>  
>  man1/%.1: man/%.pod.1 Makefile
>  	$(INSTALL_DIR) $(@D)
> -	$(POD2MAN) --release=$(VERSION) --name=`echo $@ | sed 's/^man1.//'| \
> -		sed 's/.1//'` -s 1 -c "Xen" $< $@
> +	$(POD2MAN) --release=$(VERSION) --name=$* -s 1 -c "Xen" $< $@

This is a change in quoting, and while benign now maybe it would be
better to add back quotation marks?

Jan

Re: [PATCH 2/7] docs/build: Do not open-code $*

[Andrew Cooper]

On 20/04/15 12:48, Jan Beulich wrote:
>>>> On 20.04.15 at 12:49, <andrew.cooper3@citrix.com> wrote:
>> --- a/docs/Makefile
>> +++ b/docs/Makefile
>> @@ -73,13 +73,11 @@ endif
>>  
>>  man1/%.1: man/%.pod.1 Makefile
>>  	$(INSTALL_DIR) $(@D)
>> -	$(POD2MAN) --release=$(VERSION) --name=`echo $@ | sed 's/^man1.//'| \
>> -		sed 's/.1//'` -s 1 -c "Xen" $< $@
>> +	$(POD2MAN) --release=$(VERSION) --name=$* -s 1 -c "Xen" $< $@
> This is a change in quoting, and while benign now maybe it would be
> better to add back quotation marks?

Are you sure? The result of the `` was not previously quoted, which is
why I left it unquoted across the change.

If quoting were an issue, all rules would need updating for $*, $< and $@

~Andrew

Re: [PATCH 6/7] docs/build: Move install checks into individual build targets

[Jan Beulich]

>>> On 20.04.15 at 12:49, <andrew.cooper3@citrix.com> wrote:
> @@ -103,12 +88,20 @@ install: install-man-pages install-html
>  
>  # Individual file build targets
>  man1/%.1: man/%.pod.1 Makefile
> +ifdef POD2MAN

Perhaps better to use ifneq($(POD2MAN),) in such cases?

>  	@$(INSTALL_DIR) $(@D)
>  	$(POD2MAN) --release=$(VERSION) --name=$* -s 1 -c "Xen" $< $@
> +else
> +	@echo "pod2man not installed; skipping $(@F)"

Why do you strip off the directory part? Leaving it in place would
make the output even less ambiguous (and hence more helpful).

Jan

Re: [PATCH 6/7] docs/build: Move install checks into individual build targets

[Andrew Cooper]

On 20/04/15 12:57, Jan Beulich wrote:
>>>> On 20.04.15 at 12:49, <andrew.cooper3@citrix.com> wrote:
>> @@ -103,12 +88,20 @@ install: install-man-pages install-html
>>  
>>  # Individual file build targets
>>  man1/%.1: man/%.pod.1 Makefile
>> +ifdef POD2MAN
> Perhaps better to use ifneq($(POD2MAN),) in such cases?

I was following the prevailing style, but can update all instances. 
FWIW, it is not currently an issue.

>
>>  	@$(INSTALL_DIR) $(@D)
>>  	$(POD2MAN) --release=$(VERSION) --name=$* -s 1 -c "Xen" $< $@
>> +else
>> +	@echo "pod2man not installed; skipping $(@F)"
> Why do you strip off the directory part? Leaving it in place would
> make the output even less ambiguous (and hence more helpful).

Can do.

~Andrew

Re: [PATCH 2/7] docs/build: Do not open-code $*

[Jan Beulich]

>>> On 20.04.15 at 13:55, <andrew.cooper3@citrix.com> wrote:
> On 20/04/15 12:48, Jan Beulich wrote:
>>>>> On 20.04.15 at 12:49, <andrew.cooper3@citrix.com> wrote:
>>> --- a/docs/Makefile
>>> +++ b/docs/Makefile
>>> @@ -73,13 +73,11 @@ endif
>>>  
>>>  man1/%.1: man/%.pod.1 Makefile
>>>  	$(INSTALL_DIR) $(@D)
>>> -	$(POD2MAN) --release=$(VERSION) --name=`echo $@ | sed 's/^man1.//'| \
>>> -		sed 's/.1//'` -s 1 -c "Xen" $< $@
>>> +	$(POD2MAN) --release=$(VERSION) --name=$* -s 1 -c "Xen" $< $@
>> This is a change in quoting, and while benign now maybe it would be
>> better to add back quotation marks?
> 
> Are you sure? The result of the `` was not previously quoted, which is
> why I left it unquoted across the change.

The invocation via `' itself is a kind of quoting, i.e. the result will
not be subject to things like parameter expansion and filename
globbing by the shell.

> If quoting were an issue, all rules would need updating for $*, $< and $@

That's true, so perhaps still fine as is.

Jan

Re: [PATCH 1/7] docs/build: Misc cleanup

[Ian Campbell]

On Mon, 2015-04-20 at 11:49 +0100, Andrew Cooper wrote:
>  * Use $(PANDOC) from ./configure
>  * Swap '-N' for its less-obscure longer form
>  * Don't explicitly echo about markdown.  The call to markdown is emitted
>  * Whitespace cleanup
> 
> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>

Acked-by: Ian Campbell <Ian.Campbell@citrix.com>

> CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
> CC: Wei Liu <wei.liu2@citrix.com>
> ---
>  docs/Makefile |    5 ++---
>  1 file changed, 2 insertions(+), 3 deletions(-)
> 
> diff --git a/docs/Makefile b/docs/Makefile
> index 854fb50..f4c8412 100644
> --- a/docs/Makefile
> +++ b/docs/Makefile
> @@ -84,7 +84,7 @@ man5/%.5: man/%.pod.5 Makefile
>  .PHONY: clean
>  clean:
>  	$(MAKE) -C figs clean
> -	rm -rf .word_count *.aux *.dvi *.bbl *.blg *.glo *.idx *~ 
> +	rm -rf .word_count *.aux *.dvi *.bbl *.blg *.glo *.idx *~
>  	rm -rf *.ilg *.log *.ind *.toc *.bak *.tmp core
>  	rm -rf html txt pdf
>  	rm -rf man5
> @@ -115,7 +115,6 @@ html/index.html: $(DOC_HTML) $(CURDIR)/gen-html-index INDEX
>  html/%.html: %.markdown
>  	$(INSTALL_DIR) $(@D)
>  ifdef MARKDOWN
> -	@echo "Running markdown to generate $*.html ... "
>  	$(MARKDOWN) $< > $@.tmp ; \
>  	$(call move-if-changed,$@.tmp,$@)
>  else
> @@ -189,7 +188,7 @@ endif
>  
>  pdf/%.pdf: %.markdown
>  	$(INSTALL_DIR) $(@D)
> -	pandoc -N --toc --standalone $< --output $@
> +	$(PANDOC) --number-sections --toc --standalone $< --output $@
>  
>  ifeq (,$(findstring clean,$(MAKECMDGOALS)))
>  $(XEN_ROOT)/config/Docs.mk:

Re: [PATCH 2/7] docs/build: Do not open-code $*

[Ian Campbell]

On Mon, 2015-04-20 at 11:49 +0100, Andrew Cooper wrote:
> Sometimes there is already a round enough wheel to hand.

I love the double use of sed and the unescaped .'s.
> 
> No functional change.
> 
> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>

Acked-by: Ian Campbell <Ian.Campbell@citrix.com>

(I agree with the conclusion of the subthread that we needn't worry
about quoting here, at least not in isolation wrt $@ $< etc)

Re: [PATCH 3/7] docs/build: Move two rules for consistency, and comment sections

[Ian Campbell]

On Mon, 2015-04-20 at 11:49 +0100, Andrew Cooper wrote:
> No functional change.
> 
> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>

Acked-by: Ian Campbell <Ian.Campbell@citrix.com>

Re: [PATCH 4/7] docs/build: Do not use move-if-changed

[Ian Campbell]

On Mon, 2015-04-20 at 11:49 +0100, Andrew Cooper wrote:
> Nothing expensive depends on these results.

But are those uses a problem?

> 
> Also prefer $(INSTALL_DATA) over cp to get correct file attributes (see
> fb33b2b "docs: make .txt files over-writable when building from r/o sources")
> 
> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
> CC: Ian Campbell <Ian.Campbell@citrix.com>
> CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
> CC: Wei Liu <wei.liu2@citrix.com>
> ---
>  docs/Makefile |   21 +++++++--------------
>  1 file changed, 7 insertions(+), 14 deletions(-)
> 
> diff --git a/docs/Makefile b/docs/Makefile
> index 0b458f1..d31b36f 100644
> --- a/docs/Makefile
> +++ b/docs/Makefile
> @@ -116,8 +116,7 @@ html/index.html: $(DOC_HTML) $(CURDIR)/gen-html-index INDEX
>  html/%.html: %.markdown
>  	$(INSTALL_DIR) $(@D)
>  ifdef MARKDOWN
> -	$(MARKDOWN) $< > $@.tmp ; \
> -	$(call move-if-changed,$@.tmp,$@)
> +	$(MARKDOWN) $< > $@
>  else
>  	@echo "markdown not installed; skipping $*.html."
>  endif
> @@ -129,8 +128,7 @@ html/%.txt: %.txt
>  html/man/%.1.html: man/%.pod.1 Makefile
>  	$(INSTALL_DIR) $(@D)
>  ifdef POD2HTML
> -	$(POD2HTML) --infile=$< --outfile=$@.tmp
> -	$(call move-if-changed,$@.tmp,$@)
> +	$(POD2HTML) --infile=$< --outfile=$@
>  else
>  	@echo "pod2html not installed; skipping $<."
>  endif
> @@ -138,8 +136,7 @@ endif
>  html/man/%.5.html: man/%.pod.5 Makefile
>  	$(INSTALL_DIR) $(@D)
>  ifdef POD2HTML
> -	$(POD2HTML) --infile=$< --outfile=$@.tmp
> -	$(call move-if-changed,$@.tmp,$@)
> +	$(POD2HTML) --infile=$< --outfile=$@
>  else
>  	@echo "pod2html not installed; skipping $<."
>  endif
> @@ -161,19 +158,16 @@ html/hypercall/%/index.html: $(CURDIR)/xen-headers Makefile
>  
>  txt/%.txt: %.txt
>  	$(INSTALL_DIR) $(@D)
> -	cp $< $@.tmp
> -	$(call move-if-changed,$@.tmp,$@)
> +	$(INSTALL_DATA) $< $@
>  
>  txt/%.txt: %.markdown
>  	$(INSTALL_DIR) $(@D)
> -	cp $< $@.tmp
> -	$(call move-if-changed,$@.tmp,$@)
> +	$(INSTALL_DATA) $< $@
>  
>  txt/man/%.1.txt: man/%.pod.1 Makefile
>  	$(INSTALL_DIR) $(@D)
>  ifdef POD2TEXT
> -	$(POD2TEXT) $< $@.tmp
> -	$(call move-if-changed,$@.tmp,$@)
> +	$(POD2TEXT) $< $@
>  else
>  	@echo "pod2text not installed; skipping $<."
>  endif
> @@ -181,8 +175,7 @@ endif
>  txt/man/%.5.txt: man/%.pod.5 Makefile
>  	$(INSTALL_DIR) $(@D)
>  ifdef POD2TEXT
> -	$(POD2TEXT) $< $@.tmp
> -	$(call move-if-changed,$@.tmp,$@)
> +	$(POD2TEXT) $< $@
>  else
>  	@echo "pod2text not installed; skipping $<."
>  endif

Re: [PATCH 5/7] docs/build: Do not create directories if we are not going to use them

[Ian Campbell]

On Mon, 2015-04-20 at 11:49 +0100, Andrew Cooper wrote:
> and be quite about doing so; these are only intermediate directories.
> 
> No practical change, but the build log is roughly halved.
> 
> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>

Acked-by: Ian Campbell <Ian.Campbell@citrix.com>

Re: [PATCH 6/7] docs/build: Move install checks into individual build targets

[Ian Campbell]

On Mon, 2015-04-20 at 13:01 +0100, Andrew Cooper wrote:
> On 20/04/15 12:57, Jan Beulich wrote:
> >>>> On 20.04.15 at 12:49, <andrew.cooper3@citrix.com> wrote:
> >> @@ -103,12 +88,20 @@ install: install-man-pages install-html
> >>  
> >>  # Individual file build targets
> >>  man1/%.1: man/%.pod.1 Makefile
> >> +ifdef POD2MAN
> > Perhaps better to use ifneq($(POD2MAN),) in such cases?
> 
> I was following the prevailing style, but can update all instances. 
> FWIW, it is not currently an issue.

I don't really mind, ifneq seems more prevalent in other makefiles, I'm
not sure why this one uses ifdef nor really what the implications are.

> >>  	@$(INSTALL_DIR) $(@D)
> >>  	$(POD2MAN) --release=$(VERSION) --name=$* -s 1 -c "Xen" $< $@
> >> +else
> >> +	@echo "pod2man not installed; skipping $(@F)"
> > Why do you strip off the directory part? Leaving it in place would
> > make the output even less ambiguous (and hence more helpful).
> 
> Can do.

Thanks.

Re: [PATCH 7/7] docs/build: Support generation of pandoc documents

[Ian Campbell]

On Mon, 2015-04-20 at 11:49 +0100, Andrew Cooper wrote:
> pandoc is a superset of markdown
> 
> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>

Acked-by: Ian Campbell <Ian.Campbell@citrix.com>

Re: [PATCH 6/7] docs/build: Move install checks into individual build targets

[Jan Beulich]

>>> On 21.04.15 at 16:15, <ian.campbell@citrix.com> wrote:
> On Mon, 2015-04-20 at 13:01 +0100, Andrew Cooper wrote:
>> On 20/04/15 12:57, Jan Beulich wrote:
>> >>>> On 20.04.15 at 12:49, <andrew.cooper3@citrix.com> wrote:
>> >> @@ -103,12 +88,20 @@ install: install-man-pages install-html
>> >>  
>> >>  # Individual file build targets
>> >>  man1/%.1: man/%.pod.1 Makefile
>> >> +ifdef POD2MAN
>> > Perhaps better to use ifneq($(POD2MAN),) in such cases?
>> 
>> I was following the prevailing style, but can update all instances. 
>> FWIW, it is not currently an issue.
> 
> I don't really mind, ifneq seems more prevalent in other makefiles, I'm
> not sure why this one uses ifdef nor really what the implications are.

The difference becomes visible when the variable is defined but
expands to nothing. And I view it as more useful if as empty
variable means "none" than if that results in presumably very
strange build errors.

Jan

Re: [PATCH 6/7] docs/build: Move install checks into individual build targets

[Ian Campbell]

On Tue, 2015-04-21 at 15:18 +0100, Jan Beulich wrote:
> >>> On 21.04.15 at 16:15, <ian.campbell@citrix.com> wrote:
> > On Mon, 2015-04-20 at 13:01 +0100, Andrew Cooper wrote:
> >> On 20/04/15 12:57, Jan Beulich wrote:
> >> >>>> On 20.04.15 at 12:49, <andrew.cooper3@citrix.com> wrote:
> >> >> @@ -103,12 +88,20 @@ install: install-man-pages install-html
> >> >>  
> >> >>  # Individual file build targets
> >> >>  man1/%.1: man/%.pod.1 Makefile
> >> >> +ifdef POD2MAN
> >> > Perhaps better to use ifneq($(POD2MAN),) in such cases?
> >> 
> >> I was following the prevailing style, but can update all instances. 
> >> FWIW, it is not currently an issue.
> > 
> > I don't really mind, ifneq seems more prevalent in other makefiles, I'm
> > not sure why this one uses ifdef nor really what the implications are.
> 
> The difference becomes visible when the variable is defined but
> expands to nothing. And I view it as more useful if as empty
> variable means "none" than if that results in presumably very
> strange build errors.

True. Andy, will you fix these up then?

Re: [PATCH 6/7] docs/build: Move install checks into individual build targets

[Andrew Cooper]

On 21/04/15 15:23, Ian Campbell wrote:
> On Tue, 2015-04-21 at 15:18 +0100, Jan Beulich wrote:
>>>>> On 21.04.15 at 16:15, <ian.campbell@citrix.com> wrote:
>>> On Mon, 2015-04-20 at 13:01 +0100, Andrew Cooper wrote:
>>>> On 20/04/15 12:57, Jan Beulich wrote:
>>>>>>>> On 20.04.15 at 12:49, <andrew.cooper3@citrix.com> wrote:
>>>>>> @@ -103,12 +88,20 @@ install: install-man-pages install-html
>>>>>>  
>>>>>>  # Individual file build targets
>>>>>>  man1/%.1: man/%.pod.1 Makefile
>>>>>> +ifdef POD2MAN
>>>>> Perhaps better to use ifneq($(POD2MAN),) in such cases?
>>>> I was following the prevailing style, but can update all instances. 
>>>> FWIW, it is not currently an issue.
>>> I don't really mind, ifneq seems more prevalent in other makefiles, I'm
>>> not sure why this one uses ifdef nor really what the implications are.
>> The difference becomes visible when the variable is defined but
>> expands to nothing. And I view it as more useful if as empty
>> variable means "none" than if that results in presumably very
>> strange build errors.
> True. Andy, will you fix these up then?

Yes - will fix in v2.

~Andrew

Re: [PATCH 4/7] docs/build: Do not use move-if-changed

[Andrew Cooper]

On 21/04/15 15:12, Ian Campbell wrote:
> On Mon, 2015-04-20 at 11:49 +0100, Andrew Cooper wrote:
>> Nothing expensive depends on these results.
> But are those uses a problem?

Less fluff in the build logs, and less load moving files around the
filesystem.

~Andrew

Re: [PATCH 4/7] docs/build: Do not use move-if-changed

[Ian Campbell]

On Tue, 2015-04-21 at 16:00 +0100, Andrew Cooper wrote:
> On 21/04/15 15:12, Ian Campbell wrote:
> > On Mon, 2015-04-20 at 11:49 +0100, Andrew Cooper wrote:
> >> Nothing expensive depends on these results.
> > But are those uses a problem?
> 
> Less fluff in the build logs, and less load moving files around the
> filesystem.

OK, then: Acked-by: Ian Campbell <ian.campbell@citrix.com>

Ian.

[PATCH v2 6/7] docs/build: Move install checks into individual build targets

[Andrew Cooper]

For top-level targets which use more than a single program to produce content
(txt already, pdf once pandoc is supported), these current checks are
unsuitable.

By moving the the install checks to the rules which actually use the programs,
it is now possible to build a subset of a top-level target depending on the
installed programs.

As a bonus, it removes the need to recurse for txt, man-pages and pdf targets.

A side effect of this is that every individual source which cannot be
generated will have a specific message logged, giving the file and program.
As such, these message are updated to consistently report the target file
which was not generated.

Finally, update "ifdef foo" to "ifneq($(foo),)" to be more resilient to errors
caused by having foo defined as an empty string.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>

---
v2:
 * Change $(@f) to $@ for failure messages
 * Use ifneq($(foo),) over ifdef for install tests
---
 docs/Makefile |   55 ++++++++++++++++++++++++++-----------------------------
 1 file changed, 26 insertions(+), 29 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index 6de05e4..4306a95 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -41,36 +41,21 @@ build: html txt pdf man-pages figs
 html: $(DOC_HTML) html/index.html
 
 .PHONY: txt
-txt:
-ifdef POD2TEXT
-	$(MAKE) $(DOC_TXT)
-else
-	@echo "pod2text not installed; skipping text outputs."
-endif
+txt: $(DOC_TXT)
 
 .PHONY: figs
 figs:
-ifdef FIG2DEV
+ifneq ($(FIG2DEV),)
 	set -x; $(MAKE) -C figs
 else
 	@echo "fig2dev (transfig) not installed; skipping figs."
 endif
 
 .PHONY: man-pages
-man-pages:
-ifdef POD2MAN
-	$(MAKE) $(DOC_MAN1) $(DOC_MAN5)
-else
-	@echo "pod2man not installed; skipping man-pages."
-endif
+man-pages: $(DOC_MAN1) $(DOC_MAN5)
 
 .PHONY: pdf
-pdf:
-ifdef PANDOC
-	$(MAKE) $(DOC_PDF)
-else
-	@echo "pandoc not installed; skipping pdfs."
-endif
+pdf: $(DOC_PDF)
 
 .PHONY: clean
 clean:
@@ -103,22 +88,30 @@ install: install-man-pages install-html
 
 # Individual file build targets
 man1/%.1: man/%.pod.1 Makefile
+ifneq ($(POD2MAN),)
 	@$(INSTALL_DIR) $(@D)
 	$(POD2MAN) --release=$(VERSION) --name=$* -s 1 -c "Xen" $< $@
+else
+	@echo "pod2man not installed; skipping $@"
+endif
 
 man5/%.5: man/%.pod.5 Makefile
+ifneq ($(POD2MAN),)
 	@$(INSTALL_DIR) $(@D)
 	$(POD2MAN) --release=$(VERSION) --name=$* -s 5 -c "Xen" $< $@
+else
+	@echo "pod2man not installed; skipping $@"
+endif
 
 html/index.html: $(DOC_HTML) $(CURDIR)/gen-html-index INDEX
 	$(PERL) -w -- $(CURDIR)/gen-html-index -i INDEX html $(DOC_HTML)
 
 html/%.html: %.markdown
-ifdef MARKDOWN
+ifneq ($(MARKDOWN),)
 	@$(INSTALL_DIR) $(@D)
 	$(MARKDOWN) $< > $@
 else
-	@echo "markdown not installed; skipping $*.html."
+	@echo "markdown not installed; skipping $@"
 endif
 
 html/%.txt: %.txt
@@ -126,19 +119,19 @@ html/%.txt: %.txt
 	$(INSTALL_DATA) $< $@
 
 html/man/%.1.html: man/%.pod.1 Makefile
-ifdef POD2HTML
+ifneq ($(POD2HTML),)
 	@$(INSTALL_DIR) $(@D)
 	$(POD2HTML) --infile=$< --outfile=$@
 else
-	@echo "pod2html not installed; skipping $<."
+	@echo "pod2html not installed; skipping $@"
 endif
 
 html/man/%.5.html: man/%.pod.5 Makefile
-ifdef POD2HTML
+ifneq ($(POD2HTML),)
 	@$(INSTALL_DIR) $(@D)
 	$(POD2HTML) --infile=$< --outfile=$@
 else
-	@echo "pod2html not installed; skipping $<."
+	@echo "pod2html not installed; skipping $@"
 endif
 
 # For non-x86 arches exclude the subarch whole x86 arch.
@@ -165,24 +158,28 @@ txt/%.txt: %.markdown
 	$(INSTALL_DATA) $< $@
 
 txt/man/%.1.txt: man/%.pod.1 Makefile
-ifdef POD2TEXT
+ifneq ($(POD2TEXT),)
 	@$(INSTALL_DIR) $(@D)
 	$(POD2TEXT) $< $@
 else
-	@echo "pod2text not installed; skipping $<."
+	@echo "pod2text not installed; skipping $@"
 endif
 
 txt/man/%.5.txt: man/%.pod.5 Makefile
-ifdef POD2TEXT
+ifneq ($(POD2TEXT),)
 	@$(INSTALL_DIR) $(@D)
 	$(POD2TEXT) $< $@
 else
-	@echo "pod2text not installed; skipping $<."
+	@echo "pod2text not installed; skipping $@"
 endif
 
 pdf/%.pdf: %.markdown
+ifneq ($(PANDOC),)
 	@$(INSTALL_DIR) $(@D)
 	$(PANDOC) --number-sections --toc --standalone $< --output $@
+else
+	@echo "pandoc not installed; skipping $@"
+endif
 
 ifeq (,$(findstring clean,$(MAKECMDGOALS)))
 $(XEN_ROOT)/config/Docs.mk:
-- 
1.7.10.4

[PATCH v2 7/7] docs/build: Support generation of pandoc documents

[Andrew Cooper]

pandoc is a superset of markdown

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Ian Campbell <Ian.Campbell@citrix.com>

---
v2: Extend changes from previous patch
---
 docs/Makefile |   15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/docs/Makefile b/docs/Makefile
index 4306a95..9183252 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -16,19 +16,24 @@ MARKDOWNSRC-y := $(sort $(wildcard misc/*.markdown))
 
 TXTSRC-y := $(sort $(wildcard misc/*.txt))
 
+PANDOCSRC-y := $(sort $(wildcard specs/*.pandoc))
+
 # Documentation targets
 DOC_MAN1 := $(patsubst man/%.pod.1,man1/%.1,$(MAN1SRC-y))
 DOC_MAN5 := $(patsubst man/%.pod.5,man5/%.5,$(MAN5SRC-y))
 DOC_HTML := $(patsubst %.markdown,html/%.html,$(MARKDOWNSRC-y)) \
+            $(patsubst %.pandoc,html/%.html,$(PANDOCSRC-y)) \
             $(patsubst man/%.pod.1,html/man/%.1.html,$(MAN1SRC-y)) \
             $(patsubst man/%.pod.5,html/man/%.5.html,$(MAN5SRC-y)) \
             $(patsubst %.txt,html/%.txt,$(TXTSRC-y)) \
             $(patsubst %,html/hypercall/%/index.html,$(DOC_ARCHES))
 DOC_TXT  := $(patsubst %.txt,txt/%.txt,$(TXTSRC-y)) \
             $(patsubst %.markdown,txt/%.txt,$(MARKDOWNSRC-y)) \
+            $(patsubst %.pandoc,txt/%.txt,$(PANDOCSRC-y)) \
             $(patsubst man/%.pod.1,txt/man/%.1.txt,$(MAN1SRC-y)) \
             $(patsubst man/%.pod.5,txt/man/%.5.txt,$(MAN5SRC-y))
-DOC_PDF  := $(patsubst %.markdown,pdf/%.pdf,$(MARKDOWNSRC-y))
+DOC_PDF  := $(patsubst %.markdown,pdf/%.pdf,$(MARKDOWNSRC-y)) \
+            $(patsubst %.pandoc,pdf/%.pdf,$(PANDOCSRC-y))
 
 # Top level build targets
 .PHONY: all
@@ -181,6 +186,14 @@ else
 	@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
+
 ifeq (,$(findstring clean,$(MAKECMDGOALS)))
 $(XEN_ROOT)/config/Docs.mk:
 	$(error You have to run ./configure before building docs)
-- 
1.7.10.4

Re: [PATCH v2 6/7] docs/build: Move install checks into individual build targets

[Andrew Cooper]

On 21/04/15 16:47, Andrew Cooper wrote:
> For top-level targets which use more than a single program to produce content
> (txt already, pdf once pandoc is supported), these current checks are
> unsuitable.
>
> By moving the the install checks to the rules which actually use the programs,
> it is now possible to build a subset of a top-level target depending on the
> installed programs.
>
> As a bonus, it removes the need to recurse for txt, man-pages and pdf targets.
>
> A side effect of this is that every individual source which cannot be
> generated will have a specific message logged, giving the file and program.
> As such, these message are updated to consistently report the target file
> which was not generated.
>
> Finally, update "ifdef foo" to "ifneq($(foo),)" to be more resilient to errors
> caused by having foo defined as an empty string.
>
> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
>

Alternatively, the entire v2 series can be obtained from

git://xenbits.xen.org/people/andrewcoop/xen.git docs-cleanup-v2

~Andrew

Re: [PATCH 0/7] docs/build fixes

[Ian Campbell]

On Mon, 2015-04-20 at 11:49 +0100, Andrew Cooper wrote:
> This is the results of shaving a yak which started while introducing a pandoc
> document in the Migration v2 libxc series

Applied with the replacement v2 patches for the last two.