[PATCH] docs: Support building pdfs from markdown using pandoc

[PATCH] docs: Support building pdfs from markdown using pandoc

[Andrew Cooper]

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

---
Please rerun autogen as part of committing this patch.

The Xen command line parameters document is far more useful as an indexed pdf
than it is as unindexed html webpage.  Some of the markdown could do with
tweaking for better formatting, but that is a job for a Doc Day.
---
 config/Docs.mk.in |    1 +
 docs/Makefile     |   17 +++++++++++++++--
 docs/configure.ac |    1 +
 3 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/config/Docs.mk.in b/config/Docs.mk.in
index a2a72fd..497650f 100644
--- a/config/Docs.mk.in
+++ b/config/Docs.mk.in
@@ -11,4 +11,5 @@ POD2MAN             := @POD2MAN@
 POD2HTML            := @POD2HTML@
 POD2TEXT            := @POD2TEXT@
 MARKDOWN            := @MARKDOWN@
+PANDOC              := @PANDOC@
 PERL                := @PERL@
diff --git a/docs/Makefile b/docs/Makefile
index 5153bcb..46e8f22 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -28,12 +28,13 @@ DOC_TXT  := $(patsubst %.txt,txt/%.txt,$(TXTSRC-y)) \
             $(patsubst %.markdown,txt/%.txt,$(MARKDOWNSRC-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))
 
 .PHONY: all
 all: build
 
 .PHONY: build
-build: html txt man-pages figs
+build: html txt pdf man-pages figs
 
 .PHONY: html
 html: $(DOC_HTML) html/index.html
@@ -62,6 +63,14 @@ else
 	@echo "pod2man not installed; skipping man-pages."
 endif
 
+.PHONY: pdf
+pdf:
+ifdef PANDOC
+	$(MAKE) $(DOC_PDF)
+else
+	@echo "pandoc not installed; skipping pdfs."
+endif
+
 man1/%.1: man/%.pod.1 Makefile
 	$(INSTALL_DIR) $(@D)
 	$(POD2MAN) --release=$(VERSION) --name=`echo $@ | sed 's/^man1.//'| \
@@ -77,7 +86,7 @@ clean:
 	$(MAKE) -C figs clean
 	rm -rf .word_count *.aux *.dvi *.bbl *.blg *.glo *.idx *~ 
 	rm -rf *.ilg *.log *.ind *.toc *.bak *.tmp core
-	rm -rf html txt
+	rm -rf html txt pdf
 	rm -rf man5
 	rm -rf man1
 
@@ -178,6 +187,10 @@ else
 	@echo "pod2text not installed; skipping $<."
 endif
 
+pdf/%.pdf: %.markdown
+	$(INSTALL_DIR) $(@D)
+	pandoc -N --toc --standalone $< --output $@
+
 ifeq (,$(findstring clean,$(MAKECMDGOALS)))
 $(XEN_ROOT)/config/Docs.mk:
 	$(error You have to run ./configure before building docs)
diff --git a/docs/configure.ac b/docs/configure.ac
index e545b00..bc77f49 100644
--- a/docs/configure.ac
+++ b/docs/configure.ac
@@ -17,6 +17,7 @@ AX_DOCS_TOOL_PROG([FIG2DEV], [fig2dev])
 AX_DOCS_TOOL_PROG([POD2MAN], [pod2man])
 AX_DOCS_TOOL_PROG([POD2HTML], [pod2html])
 AX_DOCS_TOOL_PROG([POD2TEXT], [pod2text])
+AX_DOCS_TOOL_PROG([PANDOC], [pandoc])
 AX_DOCS_TOOL_PROGS([MARKDOWN], [markdown], [markdown markdown_py])
 
 AC_ARG_VAR([PERL], [Path to Perl parser])
-- 
1.7.10.4

Re: [PATCH] docs: Support building pdfs from markdown using pandoc

[Ian Campbell]

On Tue, 2014-06-03 at 14:13 +0100, Andrew Cooper wrote:
> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
> CC: Ian Campbell <Ian.Campbell@citrix.com>
> CC: Ian Jackson <Ian.Jackson@eu.citrix.com>

Acked + applied.

> ---
> Please rerun autogen as part of committing this patch.

Done.

> 
> The Xen command line parameters document is far more useful as an indexed pdf
> than it is as unindexed html webpage.

I moved this sentiment into the commit message proper.

Ian.