[15/23] doc: use asciidoctor to build man pages directly

Commit Message

Felipe Contreras June 21, 2021, 4:31 p.m. UTC

There's no need to use xmlto to build the man pages when modern
asciidoctor can do it by itself.

This new mode will be active only when both USE_ASCIIDOCTOR and
USE_ASCIIDOCTOR_MANPAGE are set.

Suggested-by: Bagas Sanjaya <[e-mail]>
Suggestions-by: Jeff King <[e-mail]>
Signed-off-by: Felipe Contreras <[e-mail]>
---
 Documentation/Makefile | 10 +++++++++-
 Makefile               |  4 ++++
 2 files changed, 13 insertions(+), 1 deletion(-)

Comments

Bagas Sanjaya June 22, 2021, 5:23 a.m. UTC | #1

On 21/06/21 23.31, Felipe Contreras wrote:
> +# Define USE_ASCIIDOCTOR_MANPAGE to use Asciidoctor's manual page backend
> +# instead of building manual pages from DocBook (using xmlto). Has no effect
> +# unless USE_ASCIIDOCTOR is set.
> +#

Why not just USE_ASCIIDOCTOR_MANPAGE implies USE_ASCIIDOCTOR?

Felipe Contreras June 23, 2021, 1:35 a.m. UTC | #2

Bagas Sanjaya wrote:
> On 21/06/21 23.31, Felipe Contreras wrote:
> > +# Define USE_ASCIIDOCTOR_MANPAGE to use Asciidoctor's manual page backend
> > +# instead of building manual pages from DocBook (using xmlto). Has no effect
> > +# unless USE_ASCIIDOCTOR is set.
> > +#
> 
> Why not just USE_ASCIIDOCTOR_MANPAGE implies USE_ASCIIDOCTOR?

Personally I don't see the point of USE_ASCIIDOCTOR_MANPAGE at all. The
only reason I added it was because Martin requested it [1].

It would be nice of you and Martin could make a decision about this, and
I would just implement what you decide (or other people willing to
collaborate on this).

I don't have an opinion on this.

If no decision is reached, I'll make USE_ASCIIDOCTOR_MANPAGE imply
USE_ASCIIDOCTOR as you suggest.

Cheers.

[1] https://lore.kernel.org/git/[e-mail]/

Patch

diff --git a/Documentation/Makefile b/Documentation/Makefile
index b68ab57239..e6af1848cc 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -189,6 +189,9 @@  ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
 DBLATEX_COMMON =
 XMLTO_EXTRA += --skip-validation
 XMLTO_EXTRA += -x manpage.xsl
+ifdef USE_ASCIIDOCTOR_MANPAGE
+TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage
+endif
 endif
 
 SHELL_PATH ?= $(SHELL)
@@ -324,7 +327,7 @@  mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*)
 		show_tool_names can_merge "* " || :' >mergetools-merge.txt && \
 	date >$@
 
-TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK))
+TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK):$(USE_ASCIIDOCTOR_MANPAGE))
 
 GIT-ASCIIDOCFLAGS: FORCE
 	@FLAGS='$(TRACK_ASCIIDOCFLAGS)'; \
@@ -349,8 +352,13 @@  $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
 $(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<
 
+ifdef TXT_TO_MAN
+%.1 %.5 %.7 : %.txt $(ASCIIDOC_DEPS)
+	$(QUIET_ASCIIDOC)$(TXT_TO_MAN) -o $@ $<
+else
 %.1 %.5 %.7 : %.xml $(wildcard manpage*.xsl)
 	$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
+endif
 
 %.xml : %.txt $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<
diff --git a/Makefile b/Makefile
index 7588c43f05..ab3fa362b7 100644
--- a/Makefile
+++ b/Makefile
@@ -281,6 +281,10 @@  all::
 # Define USE_ASCIIDOCTOR to use Asciidoctor instead of AsciiDoc to build the
 # documentation.
 #
+# Define USE_ASCIIDOCTOR_MANPAGE to use Asciidoctor's manual page backend
+# instead of building manual pages from DocBook (using xmlto). Has no effect
+# unless USE_ASCIIDOCTOR is set.
+#
 # Define ASCIIDOCTOR_EXTENSIONS_LAB to point to the location of the Asciidoctor
 # Extensions Lab if you have it available.
 #