[Xen-changelog] [xen master] docs: allow writing man pages in markdown

[patchbot@xxxxxxx]

commit 46cac638ebf40fc601e16b52490538805b22b279
Author:     Cédric Bosdonnat <cbosdonnat@xxxxxxxx>
AuthorDate: Fri Dec 9 14:25:53 2016 +0100
Commit:     Wei Liu <wei.liu2@xxxxxxxxxx>
CommitDate: Mon Jan 9 11:04:11 2017 +0000

    docs: allow writing man pages in markdown
    
    Some of the docs/misc documents are written in markdown language.
    As an effort to cleanup man pages these documents will be converted into
    man pages. To avoid some more conversion, add rules to the docs/Makefile
    to generate man pages out of markdown files as well as pod ones.
    
    However, pandoc doesn't know how to convert man pages links. Thus the
    man links in markdown pages won't work.
    
    Signed-off-by: Cédric Bosdonnat <cbosdonnat@xxxxxxxx>
    Acked-by: Wei Liu <wei.liu2@xxxxxxxxxx>
---
 docs/Makefile | 48 ++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 42 insertions(+), 6 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index e2537e8..d3f5eb6 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -3,13 +3,14 @@ include $(XEN_ROOT)/Config.mk
 -include $(XEN_ROOT)/config/Docs.mk
 
 VERSION                := $(shell $(MAKE) -C $(XEN_ROOT)/xen 
--no-print-directory xenversion)
+DATE           := $(shell date +%Y-%m-%d)
 
 DOC_ARCHES      := arm x86_32 x86_64
 
 # Documentation sources to build
-MAN1SRC-y := $(sort $(shell find man/ -name '*.pod.1' -print))
-MAN5SRC-y := $(sort $(shell find man/ -name '*.pod.5' -print))
-MAN8SRC-y := $(sort $(shell find man/ -name '*.pod.8' -print))
+MAN1SRC-y := $(sort $(shell find man/ -regex '.*\.\(pod\|markdown\)\.1' 
-print))
+MAN5SRC-y := $(sort $(shell find man/ -regex '.*\.\(pod\|markdown\)\.5' 
-print))
+MAN8SRC-y := $(sort $(shell find man/ -regex '.*\.\(pod\|markdown\)\.8' 
-print))
 
 MARKDOWNSRC-y := $(sort $(shell find misc -name '*.markdown' -print))
 
@@ -18,11 +19,17 @@ TXTSRC-y := $(sort $(shell find misc -name '*.txt' -print))
 PANDOCSRC-y := $(sort $(shell find features/ misc/ specs/ -name '*.pandoc' 
-print))
 
 # Documentation targets
-DOC_MAN1 := $(patsubst man/%.pod.1,man1/%.1,$(MAN1SRC-y))
-DOC_MAN5 := $(patsubst man/%.pod.5,man5/%.5,$(MAN5SRC-y))
-DOC_MAN8 := $(patsubst man/%.pod.8,man8/%.8,$(MAN8SRC-y))
+DOC_MAN1 := $(patsubst man/%.pod.1,man1/%.1,$(MAN1SRC-y)) \
+               $(patsubst man/%.markdown.1,man1/%.1,$(MAN1SRC-y))
+DOC_MAN5 := $(patsubst man/%.pod.5,man5/%.5,$(MAN5SRC-y)) \
+               $(patsubst man/%.markdown.5,man5/%.5,$(MAN5SRC-y))
+DOC_MAN8 := $(patsubst man/%.pod.8,man8/%.8,$(MAN8SRC-y)) \
+               $(patsubst man/%.markdown.8,man8/%.8,$(MAN8SRC-y))
 DOC_HTML := $(patsubst %.markdown,html/%.html,$(MARKDOWNSRC-y)) \
             $(patsubst %.pandoc,html/%.html,$(PANDOCSRC-y)) \
+            $(patsubst man/%.markdown.1,html/man/%.1.html,$(MAN1SRC-y)) \
+            $(patsubst man/%.markdown.5,html/man/%.5.html,$(MAN5SRC-y)) \
+            $(patsubst man/%.markdown.8,html/man/%.8.html,$(MAN8SRC-y)) \
             $(patsubst man/%.pod.1,html/man/%.1.html,$(MAN1SRC-y)) \
             $(patsubst man/%.pod.5,html/man/%.5.html,$(MAN5SRC-y)) \
             $(patsubst man/%.pod.8,html/man/%.8.html,$(MAN8SRC-y)) \
@@ -31,6 +38,9 @@ DOC_HTML := $(patsubst 
%.markdown,html/%.html,$(MARKDOWNSRC-y)) \
 DOC_TXT  := $(patsubst %.txt,txt/%.txt,$(TXTSRC-y)) \
             $(patsubst %.markdown,txt/%.txt,$(MARKDOWNSRC-y)) \
             $(patsubst %.pandoc,txt/%.txt,$(PANDOCSRC-y)) \
+            $(patsubst man/%.markdown.1,txt/man/%.1.txt,$(MAN1SRC-y)) \
+            $(patsubst man/%.markdown.5,txt/man/%.5.txt,$(MAN5SRC-y)) \
+            $(patsubst man/%.markdown.8,txt/man/%.8.txt,$(MAN8SRC-y)) \
             $(patsubst man/%.pod.1,txt/man/%.1.txt,$(MAN1SRC-y)) \
             $(patsubst man/%.pod.5,txt/man/%.5.txt,$(MAN5SRC-y)) \
             $(patsubst man/%.pod.8,txt/man/%.8.txt,$(MAN8SRC-y))
@@ -89,6 +99,16 @@ else
        @echo "pod2man not installed; skipping $$@"
 endif
 
+man$(1)/%.$(1): man/%.markdown.$(1) Makefile
+ifneq ($(PANDOC),)
+       @$(INSTALL_DIR) $$(@D)
+       $(PANDOC) --standalone -V title=$$* -V section=$(1) \
+                     -V date="$(DATE)" -V footer="$(VERSION)" \
+                         -V header=Xen $$< -t man --output $$@
+else
+       @echo "pandoc not installed; skipping $$@"
+endif
+
 # HTML manpages
 html/man/%.$(1).html: man/%.pod.$(1) Makefile
 ifneq ($(POD2HTML),)
@@ -98,6 +118,14 @@ else
        @echo "pod2html not installed; skipping $$@"
 endif
 
+html/man/%.$(1).html: man/%.markdown.$(1) Makefile
+ifneq ($(PANDOC),)
+       @$(INSTALL_DIR) $$(@D)
+       $(PANDOC) --standalone $$< -t html --toc --output $$@
+else
+       @echo "pandoc not installed; skipping $$@"
+endif
+
 # Text manpages
 txt/man/%.$(1).txt: man/%.pod.$(1) Makefile
 ifneq ($(POD2TEXT),)
@@ -107,6 +135,14 @@ else
        @echo "pod2text not installed; skipping $$@"
 endif
 
+txt/man/%.$(1).txt: man/%.markdown.$(1) Makefile
+ifneq ($(PANDOC),)
+       @$(INSTALL_DIR) $$(@D)
+       $(PANDOC) --standalone $$< -t plain --output $$@
+else
+       @echo "pandoc not installed; skipping $$@"
+endif
+
 # Build
 .PHONY: man$(1)-pages
 man$(1)-pages: $$(DOC_MAN$(1))
--
generated by git-patchbot for /home/xen/git/xen.git#master

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxx
https://lists.xenproject.org/xen-changelog