Subject: Re: [PATCH v2 1/2] doc: add an option to have Asciidoctor build man pages directly

From: Junio C Hamano <[email-masked]>
Date: Fri, 14 May 2021 12:58:12 +0900

> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 2aae4c9cbb..891181c0f3 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -192,10 +192,16 @@ ASCIIDOC_HTML = xhtml5
>  ASCIIDOC_DOCBOOK = docbook5
>  ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
>  ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
> -ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
> +TXT_TO_HTML += -alitdd='&\#x2d;&\#x2d;'
> +TXT_TO_XML  += -alitdd='&\#x2d;&\#x2d;'
>  DBLATEX_COMMON =
>  XMLTO_EXTRA += --skip-validation
>  XMLTO_EXTRA += -x manpage.xsl
> +ifdef USE_ASCIIDOCTOR_MANPAGE
> +TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage
> +TXT_TO_MAN += -aplus='+'
> +TXT_TO_MAN += -alitdd='\--'
> +endif
>  endif

This hunk is wholly inside USE_ASCIIDOCTOR and deals with {litdd}
and {plus}, which are defined in asciidoc.conf that is not read by
Asciidoctor, so we'd need to be careful to keep these three places
(i.e. TXT_TO_HTML, TXT_TO_XML and TXT_TO_MAN) in sync with the
asciidoct.conf file.

It is curious that {plus} for Asciidoctor is deffined only for
manpages and HTML/XML side lacks the definition.  Intended?

It seems that the latter has several more "attributes" defined that
we do not replicate in the Makefile---I wonder if that is a sign
that we can get rid of entries for asterisk, caret, startsb,
etc. from asciidoc.conf?

Thanks.