Subject: Re: [PATCH 3/4] Documentation: move some AsciiDoc parameters into variables

From: Junio C Hamano <[email-masked]>
Date: Wed, 15 Oct 2014 13:43:49 -0700

"brian m. carlson" <[email-masked]> writes:

> Asciidoctor takes slightly different arguments from AsciiDoc in some
> cases.  It has a different name for the HTML backend and the "docbook"
> backend produces DocBook 5, not DocBook 4.5.  Also, Asciidoctor does not
> accept the -f option.  Move these values into variables so that they can
> be overridden by users wishing to use Asciidoctor instead of Asciidoc.
>
> Signed-off-by: brian m. carlson <[email-masked]>
> ---

I think it makes sense to make these customizable, but I wonder if
it makes the result easier to maintain if we make units of logical
definitions larger, e.g.

	ASCIIDOC = asciidoc
        TXT_TO_MANHTML = $(ASCIIDOC) -b xhtml11 -d manpage $(ASCIIDOC_CONF)
        TXT_TO_ARTICLE = $(ASCIIDOC) -b docbook -d article
	...

ASCIIDOC_EXTRA may want to apply all of them, even though I see that
we do not feed it to OBSOLETE_HTML right now.  It may also be that
$(ASCIIDOC_CONF) and -agit_version=$(GIT_VERSION) could be shared
among the ones that currently do not have.

Then the above would become something like:

	ASCIIDOC = asciidoc
	ASCIIDOC_COMMON = $(ASCIIDOC) \
        	$(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) -agit_version=$(GIT_VERSION)
        TXT_TO_MANHTML = $(ASCIIDOC_COMMON) -b xhtml11 -d manpage
        ...

and would further simplify this part

>  $(MAN_HTML): %.html : %.txt asciidoc.conf
>  	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
> -	$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \
> +	$(ASCIIDOC) -b $(ASCIIDOC_HTML) -d manpage $(ASCIIDOC_CONF) \
>  		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \

into just

	$(TXT_TO_MANHTML) -o $@+ $<

After all, our output formats are fairly limited, I would think.
Are there too many different variants and exceptions to make such an
approach infeasible?