Add code for processing markdown man pages.
--- a/make/launcher/LauncherCommon.gmk Fri Nov 23 12:20:06 2018 +0100
+++ b/make/launcher/LauncherCommon.gmk Fri Nov 23 12:21:47 2018 +0100
@@ -23,8 +23,9 @@
# questions.
#
+include Modules.gmk
include JdkNativeCompilation.gmk
-include Modules.gmk
+include ProcessMarkdown.gmk
# Tell the compiler not to export any functions unless declared so in
# the source code. On Windows, this is the default and cannot be changed.
@@ -213,4 +214,67 @@
)
TARGETS += $(MAN_PAGE_TARGETS)
+
+else
+ # Create dynamic man pages from markdown
+
+ PANDOC_FILTER := $(SUPPORT_OUTPUTDIR)/docs/pandoc-manpage-filter
+ PANDOC_FILTER_SETUP := $(SUPPORT_OUTPUTDIR)/docs/_pandoc_filter_setup.marker
+ PANDOC_FILTER_JAVASCRIPT := $(TOPDIR)/make/scripts/pandoc-manpage-filter.js
+
+ # Create a usable instance of the wrapper script that calls the pandoc filter
+ # (which is written in javascript).
+ $(eval $(call SetupTextFileProcessing, CREATE_PANDOC_FILTER, \
+ SOURCE_FILES := $(TOPDIR)/make/scripts/pandoc-manpage-filter.sh.template, \
+ OUTPUT_FILE := $(PANDOC_FILTER), \
+ REPLACEMENTS := \
+ @@BOOT_JDK@@ => $(BOOT_JDK) ; \
+ @@TOPDIR@@ => $(TOPDIR) ; \
+ @@JJS_FLAGS@@ => $(addprefix -J, $(JAVA_FLAGS_SMALL)), \
+ ))
+
+ # Created script must be made executable
+ $(PANDOC_FILTER_SETUP): $(CREATE_PANDOC_FILTER)
+ $(CHMOD) a+rx $(PANDOC_FILTER)
+ $(TOUCH) $@
+
+ # The norm in man pages is to display code literals as bold, but pandoc
+ # "correctly" converts these constructs (encoded in markdown using `...`
+ # or ```...```) to \f[C]. Ideally, we should use the filter to encapsulate
+ # the Code/CodeBlock in Strong. While this works for Code, pandoc cannot
+ # correctly render man page output for CodeBlock wrapped in Strong. So we
+ # take the easy way out, and post-process the troff output, replacing
+ # \f[C] with \f[CB]. This has the added benefit of working correctly on
+ # pandoc prior to version 2.0, which cannot properly produced nested
+ # formatting in man pages (see https://github.com/jgm/pandoc/issues/3568).
+ #
+ # As of pandoc 2.3, the termination of formatting is still broken
+ # (see https://github.com/jgm/pandoc/issues/4973). We need to replace
+ # \f[] with \f[R].
+ MAN_POST_PROCESS := $(SED) -e 's/\\f\[C\]/\\f\[CB\]/g' \
+ -e 's/\\f\[\]/\\f\[R\]/g'
+
+ # We assume all man pages should reside in section 1
+
+ # Generate man pages from markdown
+ MAN_$(MODULE) := $(call FindModuleManDirs, $(MODULE))
+
+ $(foreach d, $(MAN_$(MODULE)), \
+ $(if $(filter %.md, $(call CacheFind, $d)), \
+ $(eval $(MODULE)_$d_NAME := MAN_TO_TROFF_$(MODULE)_$(strip $(call RelativePath, $d, $(TOPDIR)))) \
+ $(eval $(call SetupProcessMarkdown, $($(MODULE)_$d_NAME), \
+ SRC := $d, \
+ FILES := $(filter %.md, $(call CacheFind, $d)), \
+ DEST := $(SUPPORT_OUTPUTDIR)/modules_man/$(MODULE)/man1, \
+ FORMAT := man, \
+ EXTRA_DEPS := $(PANDOC_FILTER_SETUP) \
+ $(PANDOC_FILTER_JAVASCRIPT), \
+ FILTER := $(PANDOC_FILTER), \
+ POST_PROCESS := $(MAN_POST_PROCESS), \
+ REPLACEMENTS := @@VERSION_SHORT@@ => $(VERSION_SHORT), \
+ )) \
+ $(eval MAN_PAGE_TARGETS += $($($(MODULE)_$d_NAME))) \
+ ) \
+ )
+ TARGETS += $(MAN_PAGE_TARGETS)
endif