Re: "docs: stop using asciidoc no-inline-literal" breaks asciidoc 8.2.5

From: Junio C Hamano <gitster@pobox.com>
Date: May 29, 2012, 19:45 UTC
Message-ID: <7vzk8q3h5c.fsf@alter.siamese.dyndns.org>
In-Reply-To: <CACBZZX5iOB5PCZUCX5ksR4hpw+DTLTaP4jOnyHAJ8hZVe9xo5w@mail.gmail.com>

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> I think it's too soon to break the stock toolchain on systems as
> recent as RHEL 5.5 in the name of slightly nicer asciidoc syntax.

It is debatable if any version of distribution can be called "recent" if they ship 5 year old version of software that is updated fairly often, though.

> We could also keep the nice syntax and have some simple sed-based
> pre-processor that converts the syntax to the older and more widely
> supported version.

No, let's not go there. I do not see any reason to believe that such a sed script would do an equally good or better job as native AsciiDoc implementation to deal with inline-literals. That means we would end up writing our documentation with a subset of newer AsciiDoc that the custom sed script can grok---which defeats the purpose of the whole exercise.

> Or we could just decide to break RHEL 5 and systems released at a
> similar time, but that isn't what the patch suggested it was doing, so
> we should probably step back and ponder whether that's something we
> want to do.

Very true. Jeff, how do we want to proceed? For the upcoming release, I am inclined to say that we would revert 6cf378f (docs: stop using asciidoc no-inline-literal, 2012-04-26). We would still need to double check the result, though. Documentation updates that came after it are written assuming "inline-literal" behaviour, and parts we may have "fixed" with the commit will format to their old rendition.