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

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 15, 2014, 20:43 UTC
Message-ID: <xmqq61flvzay.fsf@gitster.dls.corp.google.com>
In-Reply-To: <1413070656-241955-4-git-send-email-sandals@crustytoothpaste.net>

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

Show 8 quoted lines

> 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 <sandals@crustytoothpaste.net>
> ---

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

Show 5 quoted lines

>  $(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?