perf docs: Fix build with asciidoctor
cover perf docs: Fix build with asciidoctor
Although I made a minor fix in 2023 for asciidoctor builds, I missed an earlier regression from 2020 that had been fixed locally in the Debian package but not upstream. I'm sending 2 more fixes that should make all manual pages build properly with asciidoctor.
However, given that asciidoctor support has been broken upstream for nearly 5 years now, it might make more sense to remove it instead. We only moved to asciidoctor in Debian to remove a Python 2 dependency. Since asciidoc was ported to Python 3 that's no longer a concern.
Ben.
Ben Hutchings (2):
perf docs: Fix build with asciidoctor
perf docs: Fix perf-check manual page built with asciidoctor
tools/perf/Documentation/Makefile | 17 +++++++++-------- tools/perf/Documentation/perf-check.txt | 2 +- 2 files changed, 10 insertions(+), 9 deletions(-)
PATCH 1/2 perf docs: Fix build with asciidoctor
Currently we unconditionally add "--unsafe -f asciidoc.conf" to ASCIIDOC_EXTRA, but asciidoctor doesn't support these options.
Make all the ASCIIDOC_* variable assignments conditional on whether USE_ASCIIDOCTOR is set.
--- tools/perf/Documentation/Makefile | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-)
tools/perf/Documentation/Makefile +9 -8
@@ -44,17 +44,11 @@ man1dir=$(mandir)/man1 man5dir=$(mandir)/man5 man7dir=$(mandir)/man7 +ifndef USE_ASCIIDOCTOR ASCIIDOC=asciidoc ASCIIDOC_EXTRA += --unsafe -f asciidoc.conf ASCIIDOC_HTML = xhtml11 -MANPAGE_XSL = manpage-normal.xsl -XMLTO_EXTRA = -INSTALL?=install -RM ?= rm -f -DOC_REF = origin/man -HTML_REF = origin/html - -ifdef USE_ASCIIDOCTOR +else ASCIIDOC = asciidoctor ASCIIDOC_EXTRA += -a compat-mode ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
@@ -62,6 +56,13 @@ ASCIIDOC_EXTRA += -a mansource="perf" -a manmanual="perf Manual" ASCIIDOC_HTML = xhtml5 endif +MANPAGE_XSL = manpage-normal.xsl +XMLTO_EXTRA = +INSTALL?=install +RM ?= rm -f +DOC_REF = origin/man +HTML_REF = origin/html + infodir?=$(prefix)/share/info MAKEINFO=makeinfo INSTALL_INFO=install-info
PATCH 2/2 perf docs: Fix perf-check manual page built with asciidoctor
In reply to Ben Hutchingsasciidoctor is more picky than asciidoc about the length of heading underlines, and currently mis-parses perf-check.txt:
ASCIIDOC perf-check.1
asciidoctor: ERROR: perf-check.txt: line 1: non-conforming manpage title
asciidoctor: ERROR: perf-check.txt: line 1: name section expected
asciidoctor: WARNING: perf-check.txt: line 2: unterminated example block
asciidoctor: WARNING: perf-check.txt: line 5: unterminated listing block
Fix the length of the title underline so it works properly.
--- tools/perf/Documentation/perf-check.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
tools/perf/Documentation/perf-check.txt +1 -1
@@ -1,5 +1,5 @@ perf-check(1) -=============== +============= NAME ----