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), \ |