docs: Support building pdfs from markdown using pandoc

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

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-by: Ian Campbell <ian.campbell@citrix.com>
[ ijc -- reran autogen.sh ]

diff --git a/config/Docs.mk.in b/config/Docs.mk.in
index a2a72fdcc58443dd432042c425633f8f9a4190d8..497650f6d8a5189701fd9df8c8b70a4810327bb6 100644 (file)
--- 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 5153bcbe4f6a4f597898cfb401b75361bf74d27c..46e8f2264a7a97c4c21579f5a6719bff592ccf61 100644 (file)
--- 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 b/docs/configure
index d76e4d43e6b0eacdbfc8c38ca45ee4ca4491d3f9..c36e249fb2c6f3bc3efcb1060c1f02dd0ac5bd8b 100755 (executable)
--- a/docs/configure
+++ b/docs/configure
@@ -589,6 +589,7 @@ ac_subst_vars='LTLIBOBJS
 LIBOBJS
 PERL
 MARKDOWN
+PANDOC
 POD2TEXT
 POD2HTML
 POD2MAN
@@ -642,6 +643,7 @@ FIG2DEV
 POD2MAN
 POD2HTML
 POD2TEXT
+PANDOC
 MARKDOWN
 PERL'
 
@@ -1254,6 +1256,7 @@ Some influential environment variables:
   POD2MAN     Path to pod2man tool
   POD2HTML    Path to pod2html tool
   POD2TEXT    Path to pod2text tool
+  PANDOC      Path to pandoc tool
   MARKDOWN    Path to markdown tool
   PERL        Path to Perl parser
 
@@ -1934,6 +1937,55 @@ fi
 
 
 
+    # Extract the first word of "pandoc", so it can be a program name with args.
+set dummy pandoc; ac_word=$2
+{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
+$as_echo_n "checking for $ac_word... " >&6; }
+if ${ac_cv_path_PANDOC+:} false; then :
+  $as_echo_n "(cached) " >&6
+else
+  case $PANDOC in
+  [\\/]* | ?:[\\/]*)
+  ac_cv_path_PANDOC="$PANDOC" # Let the user override the test with a path.
+  ;;
+  *)
+  as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
+for as_dir in $PATH
+do
+  IFS=$as_save_IFS
+  test -z "$as_dir" && as_dir=.
+    for ac_exec_ext in '' $ac_executable_extensions; do
+  if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
+    ac_cv_path_PANDOC="$as_dir/$ac_word$ac_exec_ext"
+    $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
+    break 2
+  fi
+done
+  done
+IFS=$as_save_IFS
+
+  ;;
+esac
+fi
+PANDOC=$ac_cv_path_PANDOC
+if test -n "$PANDOC"; then
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: $PANDOC" >&5
+$as_echo "$PANDOC" >&6; }
+else
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
+$as_echo "no" >&6; }
+fi
+
+
+    if ! test -x "$ac_cv_path_PANDOC"; then :
+
+        { $as_echo "$as_me:${as_lineno-$LINENO}: WARNING: pandoc is not available so some documentation won't be built" >&5
+$as_echo "$as_me: WARNING: pandoc is not available so some documentation won't be built" >&2;}
+
+fi
+
+
+
     for ac_prog in markdown markdown_py
 do
   # Extract the first word of "$ac_prog", so it can be a program name with args.

diff --git a/docs/configure.ac b/docs/configure.ac
index e545b003dd8c38caf804b910572f2096e75022d5..bc77f497c3ca8ecfac3e2fea8e3fe8535dbae345 100644 (file)
--- 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])