From: "Cédric Bosdonnat" <cbosdonnat@suse.com>
To: xen-devel@lists.xen.org
Cc: "Andrew Cooper" <andrew.cooper3@citrix.com>,
"Ian Jackson" <ian.jackson@eu.citrix.com>,
"Wei Liu" <wei.liu2@citrix.com>,
"Cédric Bosdonnat" <cbosdonnat@suse.com>
Subject: [PATCH 01/11] docs: allow writing man pages in markdown
Date: Fri, 9 Dec 2016 17:17:04 +0100 [thread overview]
Message-ID: <20161209161714.23866-2-cbosdonnat@suse.com> (raw)
In-Reply-To: <20161209161714.23866-1-cbosdonnat@suse.com>
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@suse.com>
---
docs/Makefile | 48 ++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 42 insertions(+), 6 deletions(-)
diff --git a/docs/Makefile b/docs/Makefile
index e2537e8755..d3f5eb607c 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))
--
2.11.0
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
next prev parent reply other threads:[~2016-12-09 16:17 UTC|newest]
Thread overview: 31+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-12-09 16:17 [PATCH 00/11] Convert a few docs/misc pages into man pages Cédric Bosdonnat
2016-12-09 16:17 ` Cédric Bosdonnat [this message]
2017-01-04 17:55 ` [PATCH 01/11] docs: allow writing man pages in markdown Wei Liu
2016-12-09 16:17 ` [PATCH 02/11] docs: add rules for man 7 section Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2017-01-05 12:00 ` Wei Liu
2016-12-09 16:17 ` [PATCH 03/11] docs: xl-network-configuration turns into a man Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 04/11] docs: convert xl-disk-configuration into a man page Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 05/11] docs: move vbd-interface from misc to man Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 06/11] docs: move xl-numa-placement.markdown to man7 Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 07/11] docs: move vtpm from misc to man Cédric Bosdonnat
2016-12-14 21:08 ` Daniel De Graaf
2016-12-19 10:45 ` Cedric Bosdonnat
2016-12-09 16:17 ` [PATCH 08/11] docs: convert vtpmmgr into a pod man page Cédric Bosdonnat
2016-12-09 16:17 ` [PATCH 09/11] docs: convert misc/channel.txt into xen-pv-channel " Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 10/11] docs: move pci-device-reservations from misc to man Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 11/11] docs: convert tscmode.txt into man page Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2017-01-04 15:07 ` [PATCH 00/11] Convert a few docs/misc pages into man pages Wei Liu
2017-01-04 15:49 ` Cedric Bosdonnat
2017-01-05 15:01 ` Wei Liu
2017-01-05 15:12 ` Cedric Bosdonnat
2017-01-05 15:19 ` Wei Liu
2017-01-09 10:39 ` Cedric Bosdonnat
2017-01-09 11:07 ` Wei Liu
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20161209161714.23866-2-cbosdonnat@suse.com \
--to=cbosdonnat@suse.com \
--cc=andrew.cooper3@citrix.com \
--cc=ian.jackson@eu.citrix.com \
--cc=wei.liu2@citrix.com \
--cc=xen-devel@lists.xen.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.