|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [Xen-devel] [PATCH 3/4] docs/man: Fix/simplify generation of manpages
The original intent of this patch was to rename xen-vbd-interface.markdown.7
to xen-vbd-interface.pandoc.7 to remove the final markdown file from the docs/
tree.
The DOC_MANx lists are broken. They contain MANxSRC-y twice, the first half
with a partial %.pod substituation, and the second half with a partial
%.markdown substitution. This is also the root cause behind the filtering
activity in the uninstall-man$(i)-pages rule.
Furthermore, the logic for generating the manpage targets is unnecesserily
repetative, owing to the layout of source files in the man/ directory.
Therefore, tackle the problem by renaming all of our manpage source files from
"$FORMAT.$SECTION" to "$SECTION.$FORMAT". For the two xl.cfg.5 and xl.1 which
are preprocessed by autoconf to contain path information, this requires
updating configure.ac and .gitignore. The markdown to pandoc conversion is
performed as well, as it is also a straight rename.
An ancillary benefit of this renaming is that text editors stand a chance of
being able to work out the correct mode to use.
As for the makefile:
1) Break the MAN_SECTIONS list out of the GENERATE_MANPAGE_RULES loop, as we
are going to use it a second time.
2) Do away with the individaul MANxSRC-y variables. Use a single list,
derived from all *.pod and *.pandoc files, with their format suffixes
removed.
3) Use a $(foreach ...) to generate the DOC_MANx lists, filling them with the
correct content.
4) The DOC_HTML and DOC_TXT can now include all manpages with a single
substitution, as they don't need to separate the manpages by
section-numbered-directory.
5) Fix up the filenames in the manpage metarule to match the renaming.
No functional change.
Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
---
CC: George Dunlap <George.Dunlap@xxxxxxxxxxxxx>
CC: Ian Jackson <ian.jackson@xxxxxxxxxx>
CC: Jan Beulich <JBeulich@xxxxxxxx>
CC: Konrad Rzeszutek Wilk <konrad.wilk@xxxxxxxxxx>
CC: Stefano Stabellini <sstabellini@xxxxxxxxxx>
CC: Tim Deegan <tim@xxxxxxx>
CC: Wei Liu <wei.liu2@xxxxxxxxxx>
CC: Julien Grall <julien.grall@xxxxxxx>
AFAICT, the only reason the build doesn't get a hard failure is because
the DOC_MANx lists end causing the man$(x)-page targets to gain build
dependences on the (un-substituted) source files.
---
.gitignore | 4 +-
docs/Makefile | 52 +++++++---------------
docs/configure | 6 +--
docs/configure.ac | 4 +-
...ons.pod.7 => xen-pci-device-reservations.7.pod} | 0
.../{xen-pv-channel.pod.7 => xen-pv-channel.7.pod} | 0
docs/man/{xen-tscmode.pod.7 => xen-tscmode.7.pod} | 0
...rface.markdown.7 => xen-vbd-interface.7.pandoc} | 0
docs/man/{xen-vtpm.pod.7 => xen-vtpm.7.pod} | 0
docs/man/{xen-vtpmmgr.pod.7 => xen-vtpmmgr.7.pod} | 0
.../{xenstore-chmod.pod.1 => xenstore-chmod.1.pod} | 0
docs/man/{xenstore-ls.pod.1 => xenstore-ls.1.pod} | 0
.../{xenstore-read.pod.1 => xenstore-read.1.pod} | 0
.../{xenstore-write.pod.1 => xenstore-write.1.pod} | 0
docs/man/{xenstore.pod.1 => xenstore.1.pod} | 0
docs/man/{xentop.pod.1 => xentop.1.pod} | 0
docs/man/{xentrace.pod.8 => xentrace.8.pod} | 0
...xentrace_format.pod.1 => xentrace_format.1.pod} | 0
...iguration.pod.5 => xl-disk-configuration.5.pod} | 0
...ration.pod.5 => xl-network-configuration.5.pod} | 0
...uma-placement.pod.7 => xl-numa-placement.7.pod} | 0
docs/man/{xl.pod.1.in => xl.1.pod.in} | 0
docs/man/{xl.cfg.pod.5.in => xl.cfg.5.pod.in} | 0
docs/man/{xl.conf.pod.5 => xl.conf.5.pod} | 0
.../{xlcpupool.cfg.pod.5 => xlcpupool.cfg.5.pod} | 0
25 files changed, 23 insertions(+), 43 deletions(-)
rename docs/man/{xen-pci-device-reservations.pod.7 =>
xen-pci-device-reservations.7.pod} (100%)
rename docs/man/{xen-pv-channel.pod.7 => xen-pv-channel.7.pod} (100%)
rename docs/man/{xen-tscmode.pod.7 => xen-tscmode.7.pod} (100%)
rename docs/man/{xen-vbd-interface.markdown.7 => xen-vbd-interface.7.pandoc}
(100%)
rename docs/man/{xen-vtpm.pod.7 => xen-vtpm.7.pod} (100%)
rename docs/man/{xen-vtpmmgr.pod.7 => xen-vtpmmgr.7.pod} (100%)
rename docs/man/{xenstore-chmod.pod.1 => xenstore-chmod.1.pod} (100%)
rename docs/man/{xenstore-ls.pod.1 => xenstore-ls.1.pod} (100%)
rename docs/man/{xenstore-read.pod.1 => xenstore-read.1.pod} (100%)
rename docs/man/{xenstore-write.pod.1 => xenstore-write.1.pod} (100%)
rename docs/man/{xenstore.pod.1 => xenstore.1.pod} (100%)
rename docs/man/{xentop.pod.1 => xentop.1.pod} (100%)
rename docs/man/{xentrace.pod.8 => xentrace.8.pod} (100%)
rename docs/man/{xentrace_format.pod.1 => xentrace_format.1.pod} (100%)
rename docs/man/{xl-disk-configuration.pod.5 => xl-disk-configuration.5.pod}
(100%)
rename docs/man/{xl-network-configuration.pod.5 =>
xl-network-configuration.5.pod} (100%)
rename docs/man/{xl-numa-placement.pod.7 => xl-numa-placement.7.pod} (100%)
rename docs/man/{xl.pod.1.in => xl.1.pod.in} (100%)
rename docs/man/{xl.cfg.pod.5.in => xl.cfg.5.pod.in} (100%)
rename docs/man/{xl.conf.pod.5 => xl.conf.5.pod} (100%)
rename docs/man/{xlcpupool.cfg.pod.5 => xlcpupool.cfg.5.pod} (100%)
diff --git a/.gitignore b/.gitignore
index f11e613..26bc583 100644
--- a/.gitignore
+++ b/.gitignore
@@ -45,8 +45,8 @@ build-*
dist/*
docs/tmp.*
docs/html/
-docs/man/xl.cfg.pod.5
-docs/man/xl.pod.1
+docs/man/xl.cfg.5.pod
+docs/man/xl.1.pod
docs/man1/
docs/man5/
docs/man7/
diff --git a/docs/Makefile b/docs/Makefile
index 8f933cf..2867efc 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -6,12 +6,10 @@ VERSION := $(shell $(MAKE) -C $(XEN_ROOT)/xen
--no-print-directory xenversion)
DATE := $(shell date +%Y-%m-%d)
DOC_ARCHES := arm x86_32 x86_64
+MAN_SECTIONS := 1 5 7 8
# Documentation sources to build
-MAN1SRC-y := $(sort $(wildcard man/*.pod.1 man/*.markdown.1))
-MAN5SRC-y := $(sort $(wildcard man/*.pod.5 man/*.markdown.5))
-MAN7SRC-y := $(sort $(wildcard man/*.pod.7 man/*.markdown.7))
-MAN8SRC-y := $(sort $(wildcard man/*.pod.8 man/*.markdown.8))
+MAN-SRC-y := $(sort $(basename $(wildcard man/*.pod man/*.pandoc)))
MARKDOWNSRC-y := $(sort $(shell find misc -name '*.markdown' -print))
@@ -20,38 +18,20 @@ TXTSRC-y := $(sort $(shell find misc -name '*.txt' -print))
PANDOCSRC-y := $(sort $(shell find designs/ features/ misc/ process/ specs/
-name '*.pandoc' -print))
# Documentation targets
-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_MAN7 := $(patsubst man/%.pod.7,man7/%.7,$(MAN7SRC-y)) \
- $(patsubst man/%.markdown.7,man7/%.7,$(MAN7SRC-y))
-DOC_MAN8 := $(patsubst man/%.pod.8,man8/%.8,$(MAN8SRC-y)) \
- $(patsubst man/%.markdown.8,man8/%.8,$(MAN8SRC-y))
+$(foreach i,$(MAN_SECTIONS), \
+ $(eval DOC_MAN$(i) := $(patsubst man/%.$(i),man$(i)/%.$(i), \
+ $(filter %.$(i),$(MAN-SRC-y)))))
+
DOC_HTML := html/SUPPORT.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.7,html/man/%.7.html,$(MAN7SRC-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.7,html/man/%.7.html,$(MAN7SRC-y)) \
- $(patsubst man/%.pod.8,html/man/%.8.html,$(MAN8SRC-y)) \
+ $(patsubst %,html/%.html,$(MAN-SRC-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/%.markdown.1,txt/man/%.1.txt,$(MAN1SRC-y)) \
- $(patsubst man/%.markdown.5,txt/man/%.5.txt,$(MAN5SRC-y)) \
- $(patsubst man/%.markdown.7,txt/man/%.7.txt,$(MAN7SRC-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.7,txt/man/%.7.txt,$(MAN7SRC-y)) \
- $(patsubst man/%.pod.8,txt/man/%.8.txt,$(MAN8SRC-y))
+ $(patsubst %,txt/%.txt,$(MAN-SRC-y))
DOC_PDF := $(patsubst %.markdown,pdf/%.pdf,$(MARKDOWNSRC-y)) \
$(patsubst %.pandoc,pdf/%.pdf,$(PANDOCSRC-y))
@@ -99,7 +79,7 @@ distclean: clean
define GENERATE_MANPAGE_RULES
# Real manpages
-man$(1)/%.$(1): man/%.pod.$(1) Makefile
+man$(1)/%.$(1): man/%.$(1).pod Makefile
ifneq ($(POD2MAN),)
@$(INSTALL_DIR) $$(@D)
$(POD2MAN) --release=$(VERSION) --name=$$* -s $(1) -c "Xen" $$< $$@
@@ -107,7 +87,7 @@ else
@echo "pod2man not installed; skipping $$@"
endif
-man$(1)/%.$(1): man/%.markdown.$(1) Makefile
+man$(1)/%.$(1): man/%.$(1).pandoc Makefile
ifneq ($(PANDOC),)
@$(INSTALL_DIR) $$(@D)
$(PANDOC) --standalone -V title=$$* -V section=$(1) \
@@ -118,7 +98,7 @@ else
endif
# HTML manpages
-html/man/%.$(1).html: man/%.pod.$(1) Makefile
+html/man/%.$(1).html: man/%.$(1).pod Makefile
ifneq ($(POD2HTML),)
@$(INSTALL_DIR) $$(@D)
$(POD2HTML) --infile=$$< --outfile=$$@
@@ -126,7 +106,7 @@ else
@echo "pod2html not installed; skipping $$@"
endif
-html/man/%.$(1).html: man/%.markdown.$(1) Makefile
+html/man/%.$(1).html: man/%.$(1).pandoc Makefile
ifneq ($(PANDOC),)
@$(INSTALL_DIR) $$(@D)
$(PANDOC) --standalone $$< -t html --toc --output $$@
@@ -135,7 +115,7 @@ else
endif
# Text manpages
-txt/man/%.$(1).txt: man/%.pod.$(1) Makefile
+txt/man/%.$(1).txt: man/%.$(1).pod Makefile
ifneq ($(POD2TEXT),)
@$(INSTALL_DIR) $$(@D)
$(POD2TEXT) $$< $$@
@@ -143,7 +123,7 @@ else
@echo "pod2text not installed; skipping $$@"
endif
-txt/man/%.$(1).txt: man/%.markdown.$(1) Makefile
+txt/man/%.$(1).txt: man/%.$(1).pandoc Makefile
ifneq ($(PANDOC),)
@$(INSTALL_DIR) $$(@D)
$(PANDOC) --standalone $$< -t plain --output $$@
@@ -169,7 +149,7 @@ clean-man$(1)-pages:
# Uninstall
.PHONY: uninstall-man$(1)-pages
uninstall-man$(1)-pages:
- rm -f $(addprefix $(DESTDIR)$(mandir)/man$(1)/, $(filter-out %.pod.$(1)
%.markdown.$(1), $(notdir $(DOC_MAN$(1)))))
+ rm -f $(addprefix $(DESTDIR)$(mandir)/,$(DOC_MAN$(1)))
# Link buld/install/clean to toplevel rules
man-pages: man$(1)-pages
@@ -180,7 +160,7 @@ uninstall-man-pages: uninstall-man$(1)-pages
endef
# Generate manpage rules for each section
-$(foreach i,1 5 7 8,$(eval $(call GENERATE_MANPAGE_RULES,$(i))))
+$(foreach i,$(MAN_SECTIONS),$(eval $(call GENERATE_MANPAGE_RULES,$(i))))
.PHONY: install-html
install-html: html txt figs
diff --git a/docs/configure b/docs/configure
index a3b4cb6..3e0089c 100755
--- a/docs/configure
+++ b/docs/configure
@@ -1752,7 +1752,7 @@ ac_compiler_gnu=$ac_cv_c_compiler_gnu
-ac_config_files="$ac_config_files ../config/Docs.mk man/xl.cfg.pod.5
man/xl.pod.1"
+ac_config_files="$ac_config_files ../config/Docs.mk man/xl.cfg.5.pod
man/xl.1.pod"
ac_aux_dir=
for ac_dir in ../ "$srcdir"/../; do
@@ -3031,8 +3031,8 @@ for ac_config_target in $ac_config_targets
do
case $ac_config_target in
"../config/Docs.mk") CONFIG_FILES="$CONFIG_FILES ../config/Docs.mk" ;;
- "man/xl.cfg.pod.5") CONFIG_FILES="$CONFIG_FILES man/xl.cfg.pod.5" ;;
- "man/xl.pod.1") CONFIG_FILES="$CONFIG_FILES man/xl.pod.1" ;;
+ "man/xl.cfg.5.pod") CONFIG_FILES="$CONFIG_FILES man/xl.cfg.5.pod" ;;
+ "man/xl.1.pod") CONFIG_FILES="$CONFIG_FILES man/xl.1.pod" ;;
*) as_fn_error $? "invalid argument: \`$ac_config_target'" "$LINENO" 5;;
esac
diff --git a/docs/configure.ac b/docs/configure.ac
index a2929c4..5777162 100644
--- a/docs/configure.ac
+++ b/docs/configure.ac
@@ -7,8 +7,8 @@ AC_INIT([Xen Hypervisor Documentation],
m4_esyscmd([../version.sh ../xen/Makefil
AC_CONFIG_SRCDIR([misc/xen-command-line.markdown])
AC_CONFIG_FILES([
../config/Docs.mk
-man/xl.cfg.pod.5
-man/xl.pod.1
+man/xl.cfg.5.pod
+man/xl.1.pod
])
AC_CONFIG_AUX_DIR([../])
diff --git a/docs/man/xen-pci-device-reservations.pod.7
b/docs/man/xen-pci-device-reservations.7.pod
similarity index 100%
rename from docs/man/xen-pci-device-reservations.pod.7
rename to docs/man/xen-pci-device-reservations.7.pod
diff --git a/docs/man/xen-pv-channel.pod.7 b/docs/man/xen-pv-channel.7.pod
similarity index 100%
rename from docs/man/xen-pv-channel.pod.7
rename to docs/man/xen-pv-channel.7.pod
diff --git a/docs/man/xen-tscmode.pod.7 b/docs/man/xen-tscmode.7.pod
similarity index 100%
rename from docs/man/xen-tscmode.pod.7
rename to docs/man/xen-tscmode.7.pod
diff --git a/docs/man/xen-vbd-interface.markdown.7
b/docs/man/xen-vbd-interface.7.pandoc
similarity index 100%
rename from docs/man/xen-vbd-interface.markdown.7
rename to docs/man/xen-vbd-interface.7.pandoc
diff --git a/docs/man/xen-vtpm.pod.7 b/docs/man/xen-vtpm.7.pod
similarity index 100%
rename from docs/man/xen-vtpm.pod.7
rename to docs/man/xen-vtpm.7.pod
diff --git a/docs/man/xen-vtpmmgr.pod.7 b/docs/man/xen-vtpmmgr.7.pod
similarity index 100%
rename from docs/man/xen-vtpmmgr.pod.7
rename to docs/man/xen-vtpmmgr.7.pod
diff --git a/docs/man/xenstore-chmod.pod.1 b/docs/man/xenstore-chmod.1.pod
similarity index 100%
rename from docs/man/xenstore-chmod.pod.1
rename to docs/man/xenstore-chmod.1.pod
diff --git a/docs/man/xenstore-ls.pod.1 b/docs/man/xenstore-ls.1.pod
similarity index 100%
rename from docs/man/xenstore-ls.pod.1
rename to docs/man/xenstore-ls.1.pod
diff --git a/docs/man/xenstore-read.pod.1 b/docs/man/xenstore-read.1.pod
similarity index 100%
rename from docs/man/xenstore-read.pod.1
rename to docs/man/xenstore-read.1.pod
diff --git a/docs/man/xenstore-write.pod.1 b/docs/man/xenstore-write.1.pod
similarity index 100%
rename from docs/man/xenstore-write.pod.1
rename to docs/man/xenstore-write.1.pod
diff --git a/docs/man/xenstore.pod.1 b/docs/man/xenstore.1.pod
similarity index 100%
rename from docs/man/xenstore.pod.1
rename to docs/man/xenstore.1.pod
diff --git a/docs/man/xentop.pod.1 b/docs/man/xentop.1.pod
similarity index 100%
rename from docs/man/xentop.pod.1
rename to docs/man/xentop.1.pod
diff --git a/docs/man/xentrace.pod.8 b/docs/man/xentrace.8.pod
similarity index 100%
rename from docs/man/xentrace.pod.8
rename to docs/man/xentrace.8.pod
diff --git a/docs/man/xentrace_format.pod.1 b/docs/man/xentrace_format.1.pod
similarity index 100%
rename from docs/man/xentrace_format.pod.1
rename to docs/man/xentrace_format.1.pod
diff --git a/docs/man/xl-disk-configuration.pod.5
b/docs/man/xl-disk-configuration.5.pod
similarity index 100%
rename from docs/man/xl-disk-configuration.pod.5
rename to docs/man/xl-disk-configuration.5.pod
diff --git a/docs/man/xl-network-configuration.pod.5
b/docs/man/xl-network-configuration.5.pod
similarity index 100%
rename from docs/man/xl-network-configuration.pod.5
rename to docs/man/xl-network-configuration.5.pod
diff --git a/docs/man/xl-numa-placement.pod.7 b/docs/man/xl-numa-placement.7.pod
similarity index 100%
rename from docs/man/xl-numa-placement.pod.7
rename to docs/man/xl-numa-placement.7.pod
diff --git a/docs/man/xl.pod.1.in b/docs/man/xl.1.pod.in
similarity index 100%
rename from docs/man/xl.pod.1.in
rename to docs/man/xl.1.pod.in
diff --git a/docs/man/xl.cfg.pod.5.in b/docs/man/xl.cfg.5.pod.in
similarity index 100%
rename from docs/man/xl.cfg.pod.5.in
rename to docs/man/xl.cfg.5.pod.in
diff --git a/docs/man/xl.conf.pod.5 b/docs/man/xl.conf.5.pod
similarity index 100%
rename from docs/man/xl.conf.pod.5
rename to docs/man/xl.conf.5.pod
diff --git a/docs/man/xlcpupool.cfg.pod.5 b/docs/man/xlcpupool.cfg.5.pod
similarity index 100%
rename from docs/man/xlcpupool.cfg.pod.5
rename to docs/man/xlcpupool.cfg.5.pod
--
2.1.4
_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/xen-devel
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |