Add code for processing markdown man pages. ihse-manpages-branch
authorihse
Fri, 23 Nov 2018 12:21:47 +0100
branchihse-manpages-branch
changeset 57037 91a7d19da889
parent 57036 7f3d846038fc
child 57041 a9e3ec0394d3
Add code for processing markdown man pages.
make/launcher/LauncherCommon.gmk
--- 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