git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Jeff King <peff@peff.net>
To: Junio C Hamano <gitster@pobox.com>
Cc: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>,
	"Thomas Rast" <trast@inf.ethz.ch>,
	"Thomas Rast" <trast@student.ethz.ch>,
	"Carlos Martín Nieto" <cmn@elego.de>,
	"Matthieu Moy" <Matthieu.Moy@imag.fr>,
	git@vger.kernel.org
Subject: Re: "docs: stop using asciidoc no-inline-literal" breaks asciidoc 8.2.5
Date: Tue, 29 May 2012 18:01:13 -0400	[thread overview]
Message-ID: <20120529220113.GC17598@sigill.intra.peff.net> (raw)
In-Reply-To: <7vzk8q3h5c.fsf@alter.siamese.dyndns.org>

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

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

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

  reply	other threads:[~2012-05-29 22:01 UTC|newest]

Thread overview: 15+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2012-05-29 10:19 "docs: stop using asciidoc no-inline-literal" breaks asciidoc 8.2.5 Ævar Arnfjörð Bjarmason
2012-05-29 12:03 ` Thomas Rast
2012-05-29 12:31   ` Ævar Arnfjörð Bjarmason
2012-05-29 19:45     ` Junio C Hamano
2012-05-29 22:01       ` Jeff King [this message]
2012-05-29 21:56     ` Jeff King
2012-05-29 22:05       ` Dennis Kaarsemaker
2012-05-29 22:42       ` Ævar Arnfjörð Bjarmason
2012-05-29 22:51         ` Ævar Arnfjörð Bjarmason
2012-05-30  8:51         ` Jeff King
2012-05-30  9:02           ` Matthieu Moy
2012-05-30 10:17       ` [PATCH 0/3] docs: asciidoc version tweaks Jeff King
2012-05-30 10:18         ` [PATCH 1/3] INSTALL: update asciidoc recommendation Jeff King
2012-05-30 10:22         ` [PATCH 2/3] docs: drop asciidoc7compatible flag Jeff King
2012-05-30 10:22         ` [PATCH 3/3] docs: drop antique comment from Makefile Jeff King

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20120529220113.GC17598@sigill.intra.peff.net \
    --to=peff@peff.net \
    --cc=Matthieu.Moy@imag.fr \
    --cc=avarab@gmail.com \
    --cc=cmn@elego.de \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=trast@inf.ethz.ch \
    --cc=trast@student.ethz.ch \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).