documentation: fallback to asciidoctor if asciidoc (a2x) is not present

Asciidoc is EOL and only supports python2. Provide a fallback to
Asciidoctor for manpage generation.

Reference: https://github.com/digint/btrbk/pull/219

ChangeLog

@@ -17,6 +17,7 @@ btrbk-0.27.0-dev
       due to uptream bug: github.com/kdave/btrfs-progs/issues/96).
     - Always read /proc/self/mounts.
     - Resolve realpath using readlink(1).
+  * Fallback to "asciidoctor" for manpage generation (close #219).
 
 btrbk-0.26.1
 

doc/Makefile

@@ -13,6 +13,22 @@ MAN5DIR    = $(PREFIX)/share/man/man5
 GZ_MAN1 = $(addsuffix .gz,$(MAN_MAN1))
 GZ_MAN5 = $(addsuffix .gz,$(MAN_MAN5))
 
+# convert using "a2x" from asciidoc package <http://asciidoc.org>,
+# with fallback to "asciidoctor" <https://asciidoctor.org>
+ifneq (, $(shell command -v a2x 2> /dev/null))
+  # NOTE: using -L (--no-xmllint), as xmllint is a separate package on many distros.
+  ASCIIDOC_MANPAGE = a2x -L -d manpage -f manpage
+  ASCIIDOC_HTML    = asciidoc -b html -d article
+else ifneq (, $(shell command -v asciidoctor 2> /dev/null))
+  ASCIIDOC_MANPAGE = asciidoctor -d manpage -b manpage
+  ASCIIDOC_HTML    = asciidoctor -b html5 -d article
+else
+  ASCIIDOC_ERR = $(error "please install either asciidoc or asciidoctor")
+  ASCIIDOC_MANPAGE = $(ASCIIDOC_ERR)
+  ASCIIDOC_HTML    = $(ASCIIDOC_ERR)
+endif
+
+
 all: man
 man: man1 man5
 man1: $(GZ_MAN1)
@@ -37,16 +53,11 @@ clean:
 %.gz : %
 	gzip -9f $<
 
-# convert using a2x from asciidoc package: http://asciidoc.org
-
-# NOTE: we are using -L (--no-xmllint), as this xmllint is a separate
-# package on many distros.
-
 %.1 : %.1.asciidoc
-	a2x -L -d manpage -f manpage $<
+	$(ASCIIDOC_MANPAGE) $<
 
 %.5 : %.5.asciidoc
-	a2x -L -d manpage -f manpage $<
+	$(ASCIIDOC_MANPAGE) $<
 
 %.html : %.asciidoc
-	asciidoc -b html -d article -o $@ $<
+	$(ASCIIDOC_HTML) -o $@ $<