Re: [RFC suggestion] Generate manpage directly with Asciidoctor

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: May 7, 2021, 23:35 UTC
Message-ID: <6095ceb984401_cfc7208b9@natae.notmuch>
In-Reply-To: <YJWiQH2nf0B14Zy7@camp.crustytoothpaste.net>

brian m. carlson wrote:

Show 10 quoted lines

> On 2021-05-07 at 06:06:31, Bagas Sanjaya wrote:
> > So completely migrating to Asciidoctor can eliminate xmlto requirement
> > for generating manpage.
> > 
> > What do you think about above?
> 
> I didn't do this because it makes things very complicated in the
> Makefile and my goal was to minimize the needed changes and divergence.
> I'm not opposed to someone else doing it, but I expect it will be a
> bunch of work.

I don't think it would be that complicated.

This patch seems to do the trick here:

diff --git a/Documentation/Makefile b/Documentation/Makefile
index c2baad0bd8..8fa4896d22 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -189,6 +189,7 @@ ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
 DBLATEX_COMMON =
 XMLTO_EXTRA += --skip-validation
 XMLTO_EXTRA += -x manpage.xsl
+TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage
 endif
 
 SHELL_PATH ?= $(SHELL)
@@ -360,9 +361,16 @@ $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-AS
 manpage-base-url.xsl: manpage-base-url.xsl.in
 	$(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@
 
+ifdef TXT_TO_MAN
+%.1 %.5 %.7 : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
+	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
+	$(TXT_TO_MAN) -o $@+ $< && \
+	mv $@+ $@
+else
 %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)
 	$(QUIET_XMLTO)$(RM) $@ && \
 	$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
+endif
 
 %.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \

I'm sure this can be improved with some knowledge about intermediary
rules.

> It also doesn't help if you're generating more than just the manual
> pages, since generating the PDFs will definitely require xmlto and
> either dblatex or fop.  I personally prefer fop over dblatex, but folks
> have different opinions.

Huh? user-manual.pdf seems to require DBLATEX, not XMLTO.

Cheers.

-- 
Felipe Contreras