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

From: Jeff King <peff@peff.net>
Date: May 29, 2012, 22:01 UTC
Message-ID: <20120529220113.GC17598@sigill.intra.peff.net>
In-Reply-To: <7vzk8q3h5c.fsf@alter.siamese.dyndns.org>

On Tue, May 29, 2012 at 12:45:51PM -0700, Junio C Hamano wrote:

Show 10 quoted lines

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

Very much agreed; that way lies madness.

Show 12 quoted lines

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

I'd really rather keep it; I won't repeat my arguments here, but I made several in a reply to Ævar elsewhere in the thread. However, if we do revert it, then it would be really great if somebody comes up with alternate solutions to fix the long list of bugs that were fixed by 6cf378f (they are all documented in the commit message). And it would be even greater if that somebody isn't me.

I think it would also be worth figuring out when a switch would be appropriate. Moving to inline literals is obviously the way forward (it's way less error-prone, and eventually asciidoc may deprecate or drop the backwards compatibility feature themselves). So it is simply a matter of time in deciding when. If not now, then when?

-Peff