doc: allow asciidoc again

This effectively reverts 0e63843 and
173319e.

asciidoc has been revived (for a while now) and doesn't require Python 2. We
still prefer asciidoctor and fallback to asciidoc/a2x if it's not available.

Comparing the asciidoc and asciidoctor man pages, everything looks OK.

Python tends to be available more readily in distribution build environments
rather than the Ruby stack. Also, the pregenerated man pages are gone as of
f132c94.

Signed-off-by: Sam James <[email protected]>

doc/Makefile

@@ -18,8 +18,19 @@ ifeq ($(COMPRESS), yes)
 endif
 
 # convert using "asciidoctor": <https://asciidoctor.org>
-ASCIIDOCTOR_MANPAGE = asciidoctor -d manpage -b manpage
-ASCIIDOCTOR_HTML    = asciidoctor -b html5 -d article
+# fallback to "a2x" from asciidoc package: <http://asciidoc.org>
+ifneq (, $(shell command -v asciidoctor 2> /dev/null))
+  ASCIIDOC_MANPAGE = asciidoctor -d manpage -b manpage
+  ASCIIDOC_HTML    = asciidoctor -b html5 -d article
+else 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
+  ASCIIDOC_ERR = $(error "please install either asciidoc or asciidoctor")
+  ASCIIDOC_MANPAGE = $(ASCIIDOC_ERR)
+  ASCIIDOC_HTML    = $(ASCIIDOC_ERR)
+endif
 
 # reproducible builds: reference date is ":date:" attribute from asciidoc source
 date_attr = $(shell sed -rn 's/:date:\s*//p' $(1))
@@ -50,10 +61,10 @@ clean:
 	gzip -9 -n -c $< > $@
 
 %.1 : %.1.asciidoc
-	SOURCE_DATE_EPOCH=$(call source_date_epoch,$<) $(ASCIIDOCTOR_MANPAGE) -o $@ $<
+	SOURCE_DATE_EPOCH=$(call source_date_epoch,$<) $(ASCIIDOC_MANPAGE) $<
 
 %.5 : %.5.asciidoc
-	SOURCE_DATE_EPOCH=$(call source_date_epoch,$<) $(ASCIIDOCTOR_MANPAGE) -o $@ $<
+	SOURCE_DATE_EPOCH=$(call source_date_epoch,$<) $(ASCIIDOC_MANPAGE) $<
 
 %.html : %.asciidoc
-	SOURCE_DATE_EPOCH=$(call source_date_epoch,$<) $(ASCIIDOCTOR_HTML) -o $@ $<
+	SOURCE_DATE_EPOCH=$(call source_date_epoch,$<) $(ASCIIDOC_HTML) -o $@ $<

doc/install.md

@@ -9,7 +9,8 @@ file, choose one of the following methods:
 
 ### Generic Linux System
 
-Install [asciidoctor] if you want to build the documentation.
+Install [asciidoctor] or [asciidoc] if you want to build the
+documentation.
 
 Download and unpack the latest [btrbk source tarball] and type:
 
@@ -64,3 +65,4 @@ btrbk is in Void's `current` repository
 
   [btrbk source tarball]: https://digint.ch/download/btrbk/releases/
   [asciidoctor]: https://asciidoctor.org
+  [asciidoc]: https://asciidoc.org