make/Docs.gmk
branchihse-manpages-branch
changeset 57001 ffa0fd3138d7
parent 57000 03413eb7301f
child 57004 f43f68ae83ed
equal deleted inserted replaced
57000:03413eb7301f 57001:ffa0fd3138d7
   576     # Created script must be made executable
   576     # Created script must be made executable
   577     $(PANDOC_FILTER_SETUP): $(CREATE_PANDOC_FILTER)
   577     $(PANDOC_FILTER_SETUP): $(CREATE_PANDOC_FILTER)
   578 	$(CHMOD) a+rx $(PANDOC_FILTER)
   578 	$(CHMOD) a+rx $(PANDOC_FILTER)
   579 	$(TOUCH) $@
   579 	$(TOUCH) $@
   580 
   580 
   581     # Pandoc's default behavior is to convert `code` to \f[C], which do not
   581     # The norm in man pages is to display code literals as bold, but pandoc
   582     # show up in normal man page rendering (but shows correctly when generating
   582     # "correctly" converts these constructs (encoded in markdown using `...`
   583     # html). The norm for man pages is to show code as bold, so this should be
   583     # or ```...```) to \f[C]. Ideally, we should use the filter to encapsulate
   584     # transformed. However, even if we fix this in our pandoc filter, pandoc prior
   584     # the Code/CodeBlock in Strong. While this works for Code, pandoc cannot
   585     # to version 2.0 cannot properly produced nested formatting in man pages
   585     # correctly render man page output for CodeBlock wrapped in Strong. So we
   586     # (see https://github.com/jgm/pandoc/issues/3568).
   586     # take the easy way out, and post-process the troff output, replacing
   587     # As a workaround, use post-processing with sed instead.
   587     # \f[C] with \f[CB]. This has the added benefit of working correctly on
       
   588     # pandoc prior to version 2.0, which cannot properly produced nested
       
   589     # formatting in man pages (see https://github.com/jgm/pandoc/issues/3568).
   588     #
   590     #
   589     # As of pandoc 2.3, the termination of formatting is still broken
   591     # As of pandoc 2.3, the termination of formatting is still broken
   590     # (see https://github.com/jgm/pandoc/issues/4973). We need to replace
   592     # (see https://github.com/jgm/pandoc/issues/4973). We need to replace
   591     # \f[] with \f[R].
   593     # \f[] with \f[R].
   592     MAN_POST_PROCESS := $(SED) -e 's/\\f\[C\]/\\f\[CB\]/g' \
   594     MAN_POST_PROCESS := $(SED) -e 's/\\f\[C\]/\\f\[CB\]/g' \
   593         -e 's/\\f\[\]/\\f\[R\]/g'
   595         -e 's/\\f\[\]/\\f\[R\]/g'
   594 
       
   595 
   596 
   596     # We assume all man pages should reside in section 1
   597     # We assume all man pages should reside in section 1
   597 
   598 
   598     # Generate man pages from markdown
   599     # Generate man pages from markdown
   599     $(foreach m, $(ALL_MODULES), \
   600     $(foreach m, $(ALL_MODULES), \