Re: [RFC suggestion] Generate manpage directly with Asciidoctor

From: brian m. carlson <sandals@crustytoothpaste.net>
Date: May 7, 2021, 23:57 UTC
Message-ID: <YJXT7AaqCeCV4WcZ@camp.crustytoothpaste.net>
In-Reply-To: <6095ceb984401_cfc7208b9@natae.notmuch>

On 2021-05-07 at 23:35:21, Felipe Contreras wrote:

Show 36 quoted lines

> 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's not quite that simple. It requires changes to asciidoctor-extensions.rb and we also need to consider NO_MAN_BOLD_LITERAL and GNU_ROFF. The latter especially is likely to be inconvenient, since according to the Makefile, it's impossible to write man output that works across troff versions.

We will also want to preserve the ability to use xmlto because we currently have doc-diff which helps us find divergences in the behavior of AsciiDoc and Asciidoctor, many of which affect all formats, and that will be completely useless if we use two different rendering toolchains.

So, yes, this is a good start, but it's not quite as trivial as it seems.

Show 6 quoted lines

> > 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.

Ah, yes, because we do it manually instead of using xmlto.

-- 
brian m. carlson (he/him or they/them)
Houston, Texas, US