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

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

[Ævar Arnfjörð Bjarmason]

Jeff King's 6cf378f0cbe7c7f944637892caeb9058c90a185a broke my Git
build on CentOS 5.5. The patch suggests that it only breaks
compatibility with asciidoc 7 but that isn't actually the case.

The problem is that by using literals we seem to be triggering some
old bug in asciidoc related to how it balances XML tags, so e.g. for
this bit in user-manual.txt:

    - the variable `sha1` in the function signature of `get_sha1()` is `unsigned
      char *`, but is actually expected to be a pointer to `unsigned
      char[20]`.  This variable will contain the 160-bit SHA-1 of the given
      commit.  Note that whenever a SHA-1 is passed as `unsigned char *`, it
      is the binary representation, as opposed to the ASCII representation in
      hex characters, which is passed as `char *`.

We'll produce this XML:

    <simpara>
    the variable <literal>sha1</literal> in the function signature of
<literal>get_sha1()</literal> is <literal>unsigned
      char <emphasis role="strong"></literal>, but is actually
expected to be a pointer to <literal>unsigned
      char[20]</literal>.  This variable will contain the 160-bit
SHA-1 of the given
      commit.  Note that whenever a SHA-1 is passed as
<literal>unsigned char </emphasis></literal>, it
      is the binary representation, as opposed to the ASCII representation in
      hex characters, which is passed as <literal>char *</literal>.
    </simpara>

Which results in this error:

    user-manual.xml:3743: parser error : Opening and ending tag
mismatch: emphasis line 3743 and literal
      char <emphasis role="strong"></literal>, but is actually
expected to be a poin
                                             ^
    user-manual.xml:3745: parser error : Opening and ending tag
mismatch: literal line 3745 and emphasis
    mit.  Note that whenever a SHA-1 is passed as <literal>unsigned
char </emphasis>

A patch like this will hack around that:

    diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
    index 1b94207..0fc8829 100644
    --- a/Documentation/user-manual.txt
    +++ b/Documentation/user-manual.txt
    @@ -4270,9 +4270,9 @@ Two things are interesting here:
       negative numbers in case of different errors--and 0 on success.

     - the variable `sha1` in the function signature of `get_sha1()`
is `unsigned
    -  char *`, but is actually expected to be a pointer to `unsigned
    +  char {asterisk}`, but is actually expected t
       char[20]`.  This variable will contain the 160-bit SHA-1 of the given
    -  commit.  Note that whenever a SHA-1 is passed as `unsigned char *`, it
    +  commit.  Note that whenever a SHA-1 is passed as `unsigned char
{asterisk}`, it
       is the binary representation, as opposed to the ASCII representation in
       hex characters, which is passed as `char *`.

So the issue appears to be mostly related to older asciidoc in the 8.*
line incorrectly handling markup that would generate nested XML tags,
here's as far as I got with fixing it:

    $ git --no-pager diff -U0 @{u}..
    diff --git a/Documentation/config.txt b/Documentation/config.txt
    index 915cb5a..fd2f939 100644
    --- a/Documentation/config.txt
    +++ b/Documentation/config.txt
    @@ -904 +904 @@ commit.template::
    -       "`~/`" is expanded to the value of `$HOME` and "`~user/`" to the
    +       "`{tilde}/`" is expanded to the value of `$HOME` and
"`{tilde}user/`" to the
    @@ -1664 +1664 @@ pack.indexVersion::
    -If you have an old git that does not understand the version 2 `*.idx` file,
    +If you have an old git that does not understand the version 2
`{asterisk}.idx` file,
    @@ -1666 +1666 @@ cloning or fetching over a non native protocol
(e.g. "http" and "rsync")
    -that will copy both `*.pack` file and corresponding `*.idx` file from the
    +that will copy both `{asterisk}.pack` file and corresponding
`{asterisk}.idx` file from the
    @@ -1668 +1668 @@ other side may give you a repository that cannot
be accessed with your
    -older version of git. If the `*.pack` file is smaller than 2 GB, however,
    +older version of git. If the `{asterisk}.pack` file is smaller
than 2 GB, however,
    @@ -1670 +1670 @@ you can use linkgit:git-index-pack[1] on the
*.pack file to regenerate
    -the `*.idx` file.
    +the `{asterisk}.idx` file.
    @@ -1694 +1694 @@ pretty.<name>::
    -       running `git config pretty.changelog "format:* %H %s"`
    +       running `git config pretty.changelog "format:{asterisk} %H %s"`
    @@ -1696 +1696 @@ pretty.<name>::
    -       to be equivalent to running `git log "--pretty=format:* %H %s"`.
    +       to be equivalent to running `git log
"--pretty=format:{asterisk} %H %s"`.
    diff --git a/Documentation/git-check-ref-format.txt
b/Documentation/git-check-ref-format.txt
    index 98009d1..3370565 100644
    --- a/Documentation/git-check-ref-format.txt
    +++ b/Documentation/git-check-ref-format.txt
    @@ -95 +95 @@ OPTIONS
    -       enabled, <refname> is allowed to contain a single `*`
    +       enabled, <refname> is allowed to contain a single `{asterisk}`
    @@ -97 +97 @@ OPTIONS
    -       `foo/*/bar` but not `foo/bar*`).
    +       `foo/{asterisk}/bar` but not `foo/bar{asterisk}`).
    diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
    index 3bec036..5ae82f3 100644
    --- a/Documentation/git-grep.txt
    +++ b/Documentation/git-grep.txt
    @@ -252 +252 @@ Examples
    -`git grep 'time_t' -- '*.[ch]'`::
    +`git grep {apostrophe}time_t{apostrophe} \--
{apostrophe}*.[ch]{apostrophe}`::
    diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
    index 1b94207..fe86e53 100644
    --- a/Documentation/user-manual.txt
    +++ b/Documentation/user-manual.txt
    @@ -4273 +4273 @@ Two things are interesting here:
    -  char *`, but is actually expected to be a pointer to `unsigned
    +  char {asterisk}`, but is actually expected to be a pointer to `unsigned
    @@ -4275 +4275 @@ Two things are interesting here:
    -  commit.  Note that whenever a SHA-1 is passed as `unsigned char *`, it
    +  commit.  Note that whenever a SHA-1 is passed as `unsigned char
{asterisk}`, it
    @@ -4277 +4277 @@ Two things are interesting here:
    -  hex characters, which is passed as `char *`.
    +  hex characters, which is passed as `char {asterisk}`.

I suggest just ejecting this patch and trying again, these RedHat
systems are still used in a lot of environments, especially by various
companies.

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

[Thomas Rast]

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

> Jeff King's 6cf378f0cbe7c7f944637892caeb9058c90a185a broke my Git
> build on CentOS 5.5. The patch suggests that it only breaks
> compatibility with asciidoc 7 but that isn't actually the case.

The commit message of 6cf378f0 is not correct in that respect.  My
ancient 71c020c5 has the right numbers: asciidoc 8.4.1 is the one that
introduced the new inline-literal behavior.  Based on my little survey
in

  http://thread.gmane.org/gmane.comp.version-control.git/191738/focus=191790

we decided that "nobody" really uses such an old asciidoc any more.
Evidently you are a counterexample.

> I suggest just ejecting this patch and trying again, these RedHat
> systems are still used in a lot of environments, especially by various
> companies.

Do you/they have to *build* the docs, as opposed to using the prebuilt
ones coming from Junio?  Perhaps we can make it so 'make man' refuses to
run if asciidoc is too old, and give a message to the effect that you
should 'make quick-install-man' instead.

Otherwise we'll be working around the f{asterisk}{asterisk}{asterisk}ing
quoting rules for years to come.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

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

[Ævar Arnfjörð Bjarmason]

On Tue, May 29, 2012 at 2:03 PM, Thomas Rast <trast@inf.ethz.ch> wrote:
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> Jeff King's 6cf378f0cbe7c7f944637892caeb9058c90a185a broke my Git
>> build on CentOS 5.5. The patch suggests that it only breaks
>> compatibility with asciidoc 7 but that isn't actually the case.
>
> The commit message of 6cf378f0 is not correct in that respect.  My
> ancient 71c020c5 has the right numbers: asciidoc 8.4.1 is the one that
> introduced the new inline-literal behavior.  Based on my little survey
> in
>
>  http://thread.gmane.org/gmane.comp.version-control.git/191738/focus=191790
>
> we decided that "nobody" really uses such an old asciidoc any more.
> Evidently you are a counterexample.

Well, me and and others using current production RHEL releases:

    $ cat /etc/redhat-release && yum info asciidoc.noarch|grep Version
    CentOS release 5.5 (Final)
    Version    : 8.1.0
    $ cat /etc/redhat-release && yum info asciidoc.noarch|grep Version
    CentOS release 5.5 (Final)
    Version    : 8.2.5

I can't quite recall how I ended up with 8.2.5 on one of the boxes,
but it seems 8.1.0 may actually be the stock version.

>> I suggest just ejecting this patch and trying again, these RedHat
>> systems are still used in a lot of environments, especially by various
>> companies.
>
> Do you/they have to *build* the docs, as opposed to using the prebuilt
> ones coming from Junio?  Perhaps we can make it so 'make man' refuses to
> run if asciidoc is too old, and give a message to the effect that you
> should 'make quick-install-man' instead.
>
> Otherwise we'll be working around the f{asterisk}{asterisk}{asterisk}ing
> quoting rules for years to come.

I could personally change my build process to do something else, but
the reason I'm running "all doc" occasionally on this older toolchain
is to smoke out issues like these for other users on slightly older
toolchains as well.

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.

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.

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.

Personally I think having a hard dependency on a version of a software
package released more recently than 2007 (8.2.5 came out on
2007-11-18) is way too soon, it would be similar to breaking on a GCC
older than 4.2.0 which came out around the same time.

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

[Junio C Hamano]

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

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

[Jeff King]

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

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

[Jeff King]

On Tue, May 29, 2012 at 02:31:38PM +0200, Ævar Arnfjörð Bjarmason wrote:

> On Tue, May 29, 2012 at 2:03 PM, Thomas Rast <trast@inf.ethz.ch> wrote:
> > Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> >
> >> Jeff King's 6cf378f0cbe7c7f944637892caeb9058c90a185a broke my Git
> >> build on CentOS 5.5. The patch suggests that it only breaks
> >> compatibility with asciidoc 7 but that isn't actually the case.
> >
> > The commit message of 6cf378f0 is not correct in that respect.  My
> > ancient 71c020c5 has the right numbers: asciidoc 8.4.1 is the one that
> > introduced the new inline-literal behavior.  Based on my little survey
> > in

Yeah, sorry, this is my fault. It came up in discussion but I never
amended the commit message. The magic number is definitely 8.4.1.

> Well, me and and others using current production RHEL releases:
> 
>     $ cat /etc/redhat-release && yum info asciidoc.noarch|grep Version
>     CentOS release 5.5 (Final)
>     Version    : 8.1.0
>     $ cat /etc/redhat-release && yum info asciidoc.noarch|grep Version
>     CentOS release 5.5 (Final)
>     Version    : 8.2.5
> 
> I can't quite recall how I ended up with 8.2.5 on one of the boxes,
> but it seems 8.1.0 may actually be the stock version.

From my searches, there is no stock version in RHEL5 or CentOS 5. They
did not start shipping asciidoc until RHEL6, which includes 8.4.5. It's
very easy to find 3rd-party RPMs for asciidoc, which is presumably why
you have multiple versions. And these days it's easy to find 8.4.5
packaged for el5.

Can you check your yum sources? I may be wrong that asciidoc was never
part of the base system, but I can't find it in the RHEL or CentOS
package lists, and google searching turns up only 3rd-party versions.
Of course, it may also have been installed as a one-off, outside of yum,
or the yum sources changed after it was installed, so your check may
yield nothing interesting.

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

It was not intentional to break RHEL5 in particular, but it was
definitely intentional to stop working with older versions of asciidoc.
As I wrote above, I'm not sure that there _is_ an official version of
asciidoc for RHEL 5.

> Personally I think having a hard dependency on a version of a software
> package released more recently than 2007 (8.2.5 came out on
> 2007-11-18) is way too soon, it would be similar to breaking on a GCC
> older than 4.2.0 which came out around the same time.

I think that's over-simplifying. We can use old versions of gcc (or even
antique proprietary compilers) because they all accept C89 or some
reasonable variant, a standard which was mature at the time of their
writing. Asciidoc is much less mature, and the no-inline-literal syntax
sucks, and was the source of a very large number of recurring bugs. We
have to balance the pain of supporting the old versions with the pain of
leaving behind people with no other option.

So it is not just "well, this modern syntax is a little nicer". It is
fixing real documentation formatting bugs that affect all users (on old
and modern asciidoc), and closing the hole so that they don't happen
again.

And unlike compilers, it is relatively easy to work around; because the
build result is architecture independent, Junio can (and does) produce
built versions which plug into the Makefile.

I'm very sympathetic to having platform support dropped. It's annoying
for the user. But given that it's a 3rd-party install anyway (and you
can install a newer 3rd-party RPM), and that you can additionally use
"make quick-install-man" to avoid needing asciidoc entirely, and given
the sheer number of bugs this patch fixes (and prevents), to me the
balance still argues for keeping the patch.

One thing we could do better at is not silently producing crappy results
(e.g., by detecting a too-old asciidoc version during the build process,
and advising the user to upgrade or user quick-install). Or even having
a deprecation period with warning, though I feel that's less important
for a build breakage than a run-time change of behavior.

-Peff

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

[Dennis Kaarsemaker]

On di, 2012-05-29 at 17:56 -0400, Jeff King wrote:
> 
> From my searches, there is no stock version in RHEL5 or CentOS 5. They
> did not start shipping asciidoc until RHEL6, which includes 8.4.5. It's
> very easy to find 3rd-party RPMs for asciidoc, which is presumably why
> you have multiple versions. And these days it's easy to find 8.4.5
> packaged for el5. 

epel (pretty much the default 2½th party repo, maintained by the fedora
people) ships asciidoc for rhel5/centos5, but not anything newer than
8.1.x 

-- 
Dennis K.

Life is what happens to you while you're busy making other plans 
  - John Lennon

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

[Ævar Arnfjörð Bjarmason]

On Tue, May 29, 2012 at 11:56 PM, Jeff King <peff@peff.net> wrote:

> I'm very sympathetic to having platform support dropped. It's annoying
> for the user. But given that it's a 3rd-party install anyway (and you
> can install a newer 3rd-party RPM), and that you can additionally use
> "make quick-install-man" to avoid needing asciidoc entirely, and given
> the sheer number of bugs this patch fixes (and prevents), to me the
> balance still argues for keeping the patch.

To be clear I like the patch, I was just suggesting that we might want
to hold it off for a bit.

Anyway, I've tested dropping asciidoc.py from the source distribution
into compat/asciidoc.py and doing "make doc
ASCIIDOC=../compat/asciidoc.py", it seems to work.

I wonder if the easiest solution is to change the default asciidoc
invocation from "asciidoc" to a small Documentation/asciidoc.sh script
that we supply, it would check if there's an asciidoc present on the
system, whether it's sufficiently new, and if not fall back on a copy
we have in compat/.

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

[Ævar Arnfjörð Bjarmason]

On Wed, May 30, 2012 at 12:42 AM, Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
> On Tue, May 29, 2012 at 11:56 PM, Jeff King <peff@peff.net> wrote:
>
>> I'm very sympathetic to having platform support dropped. It's annoying
>> for the user. But given that it's a 3rd-party install anyway (and you
>> can install a newer 3rd-party RPM), and that you can additionally use
>> "make quick-install-man" to avoid needing asciidoc entirely, and given
>> the sheer number of bugs this patch fixes (and prevents), to me the
>> balance still argues for keeping the patch.
>
> To be clear I like the patch, I was just suggesting that we might want
> to hold it off for a bit.
>
> Anyway, I've tested dropping asciidoc.py from the source distribution
> into compat/asciidoc.py and doing "make doc
> ASCIIDOC=../compat/asciidoc.py", it seems to work.
>
> I wonder if the easiest solution is to change the default asciidoc
> invocation from "asciidoc" to a small Documentation/asciidoc.sh script
> that we supply, it would check if there's an asciidoc present on the
> system, whether it's sufficiently new, and if not fall back on a copy
> we have in compat/.

Something like this silly patch, which seems to work, but needs cleanup:

    https://github.com/avar/git/compare/git:master...avar/asciidoc-fallback

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

[Jeff King]

On Wed, May 30, 2012 at 12:42:32AM +0200, Ævar Arnfjörð Bjarmason wrote:

> Anyway, I've tested dropping asciidoc.py from the source distribution
> into compat/asciidoc.py and doing "make doc
> ASCIIDOC=../compat/asciidoc.py", it seems to work.
> 
> I wonder if the easiest solution is to change the default asciidoc
> invocation from "asciidoc" to a small Documentation/asciidoc.sh script
> that we supply, it would check if there's an asciidoc present on the
> system, whether it's sufficiently new, and if not fall back on a copy
> we have in compat/.

That makes me somewhat nervous. The asciidoc package on my system
contains 311 files. It seems probable that at least one of those files
beyond asciidoc.py is necessary for the system to work, and that it may
even depend on matching versions.

If we are going to go the route of providing an asciidoc for people
whose asciidoc is buggy, we might as well go all out and provide a
complete standalone asciidoc (or at least some subset) for those who
don't have it at all. Part of me finds that utterly gross, but part of
me likes the fact that we would be able to move our documentation and
our asciidoc interpreter in lockstep, which avoids some other bugs we
have seen in the past.  Of course, that doesn't help the rest of the
documentation toolchain (differing docbook versions have created
problems in the past, too).

I suppose the grossness would depend on how small a minimal asciidoc
distribution could be made (of those 311 files, many are documentation
and examples).

-Peff

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

[Matthieu Moy]

Jeff King <peff@peff.net> writes:

> If we are going to go the route of providing an asciidoc for people
> whose asciidoc is buggy, we might as well go all out and provide a
> complete standalone asciidoc (or at least some subset) for those who
> don't have it at all.

Perhaps a "make install-asciidoc" target that does the
wget && make && make DESTDIR=contrib/ install
(or whatever asciidoc needs to be installed)?

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

[PATCH 0/3] docs: asciidoc version tweaks

[Jeff King]

On Tue, May 29, 2012 at 05:56:13PM -0400, Jeff King wrote:

> > > The commit message of 6cf378f0 is not correct in that respect.  My
> > > ancient 71c020c5 has the right numbers: asciidoc 8.4.1 is the one that
> > > introduced the new inline-literal behavior.  Based on my little survey
> > > in
> 
> Yeah, sorry, this is my fault. It came up in discussion but I never
> amended the commit message. The magic number is definitely 8.4.1.

I think 6cf378f0 left a few other loose ends, too. Fixes to follow.

  [1/3]: INSTALL: update asciidoc recommendation
  [2/3]: docs: drop asciidoc7compatible flag
  [3/3]: docs: drop antique comment from Makefile

-Peff

[PATCH 1/3] INSTALL: update asciidoc recommendation

[Jeff King]

Since commit 6cf378f (docs: stop using asciidoc no-inline-literal),
we no longer support asciidoc versions less than 8.4.1,
which introduced inline literals. Note this in the INSTALL
document.

Signed-off-by: Jeff King <peff@peff.net>
---
 INSTALL | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/INSTALL b/INSTALL
index 87e03bb..28f34bd 100644
--- a/INSTALL
+++ b/INSTALL
@@ -161,11 +161,9 @@ Issues of note:
    makeinfo and docbook2X.  Version 0.8.3 is known to work.
 
    Building and installing the pdf file additionally requires
-   dblatex.  Version 0.2.7 with asciidoc >= 8.2.7 is known to work.
+   dblatex.  Version >= 0.2.7 is known to work.
 
-   The documentation is written for AsciiDoc 7, but by default
-   uses some compatibility wrappers to work on AsciiDoc 8. If you have
-   AsciiDoc 7, try "make ASCIIDOC7=YesPlease".
+   All formats require at least asciidoc 8.4.1.
 
    There are also "make quick-install-doc", "make quick-install-man"
    and "make quick-install-html" which install preformatted man pages
-- 
1.7.11.rc0.12.g6048c92

[PATCH 2/3] docs: drop asciidoc7compatible flag

[Jeff King]

When we made the switch to supporting asciidoc 8 in 4c7100a
(Documentation: adjust to AsciiDoc 8, 2007-06-14), we were
able to leave most of the documentation intact by defining
asciidoc7compatible.

Since commit 6cf378f (docs: stop using asciidoc no-inline-literal,
2012-04-26), we don't support versions of asciidoc older
than 8.4.1, which is when inline literals were introduced.
Therefore there is not much point in keeping our
documentation compatible with asciidoc 7.

So we are now free to drop the asciidoc7compatible flag and
update the documentation itself to assume asciidoc8.
Fortunately, doing the latter is very easy; we weren't using
any of the constructs impacted by asciidoc7compatible, so
there are no changes to make.

The reason is somewhat subtle. The asciidoc7compatible
affects only super/sub-scripts ("^" and "~") and index
terms. We don't use the latter at all. Nor we do we use the
former, but we did have to protect them from accidental
expansion in constructs like "rev^1". However, all of our
uses of "~" and "^" are either in code blocks (which are
rendered literally), or inside backticks. Prior to 6cf378f,
backticks were not inline literals, and needed proper
quoting. But post-6cf378f, we don't have to worry whether we
are using the old or new rules, as those characters are not
interpreted at all in either case.

I verified that the result of "make install-html
install-man" is identical before and after this patch on
asciidoc 8.6.7.

Signed-off-by: Jeff King <peff@peff.net>
---
It's possible that other recent versions of asciidoc might not generate
identical output, or that asciidoc7compatible might change in the future
to include some as-yet-undiscovered incompatibility (though I find that
unlikely, as it has been several years now). But in that case, I think
this is still the right thing to do, and we should update to the proper
asciidoc8 syntax.

I tweaked the configure.ac to stop setting ASCIIDOC7, since it no longer
does anything. I believe this makes the whole version check a no-op,
except for the message that is printed. It might be worth actually
checking for asciidoc >= 8.4.1 in the configure script, but I will leave
that to the folks who care about autoconf (apparently there is a
dotted-version comparison function, but it was only in autoconf 2.53 or
higher, and I have no idea what we consider recent enough autoconf).

 Documentation/Makefile | 9 ---------
 Makefile               | 6 ------
 config.mak.in          | 1 -
 configure.ac           | 7 -------
 4 files changed, 23 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 14286cb..030e2c8 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -66,12 +66,6 @@ endif
 -include ../config.mak
 
 #
-# For asciidoc ...
-#	-7.1.2,	set ASCIIDOC7
-#	8.0-,	no extra settings are needed
-#
-
-#
 # For docbook-xsl ...
 #	-1.68.1,	no extra settings are needed?
 #	1.69.0,		set ASCIIDOC_ROFF?
@@ -81,9 +75,6 @@ endif
 #	1.73.0-,	no extra settings are needed
 #
 
-ifndef ASCIIDOC7
-ASCIIDOC_EXTRA += -a asciidoc7compatible
-endif
 ifdef DOCBOOK_XSL_172
 ASCIIDOC_EXTRA += -a git-asciidoc-no-roff
 MANPAGE_XSL = manpage-1.72.xsl
diff --git a/Makefile b/Makefile
index 96ebcf9..55943a9 100644
--- a/Makefile
+++ b/Makefile
@@ -203,8 +203,6 @@ all::
 # Define NO_ST_BLOCKS_IN_STRUCT_STAT if your platform does not have st_blocks
 # field that counts the on-disk footprint in 512-byte blocks.
 #
-# Define ASCIIDOC7 if you want to format documentation with AsciiDoc 7
-#
 # Define DOCBOOK_XSL_172 if you want to format man pages with DocBook XSL v1.72
 # (not v1.73 or v1.71).
 #
@@ -1834,10 +1832,6 @@ ifndef V
 endif
 endif
 
-ifdef ASCIIDOC7
-	export ASCIIDOC7
-endif
-
 ifdef NO_INSTALL_HARDLINKS
 	export NO_INSTALL_HARDLINKS
 endif
diff --git a/config.mak.in b/config.mak.in
index b2ba710..802d342 100644
--- a/config.mak.in
+++ b/config.mak.in
@@ -28,7 +28,6 @@ VPATH = @srcdir@
 export exec_prefix mandir
 export srcdir VPATH
 
-ASCIIDOC7=@ASCIIDOC7@
 NEEDS_SSL_WITH_CRYPTO=@NEEDS_SSL_WITH_CRYPTO@
 NO_OPENSSL=@NO_OPENSSL@
 NO_CURL=@NO_CURL@
diff --git a/configure.ac b/configure.ac
index e125550..4e9012f 100644
--- a/configure.ac
+++ b/configure.ac
@@ -437,21 +437,14 @@ if test -n "$ASCIIDOC"; then
 	AC_MSG_CHECKING([for asciidoc version])
 	asciidoc_version=`$ASCIIDOC --version 2>/dev/null`
 	case "${asciidoc_version}" in
-	asciidoc' '7*)
-		ASCIIDOC7=YesPlease
-		AC_MSG_RESULT([${asciidoc_version} > 7])
-		;;
 	asciidoc' '8*)
-		ASCIIDOC7=
 		AC_MSG_RESULT([${asciidoc_version}])
 		;;
 	*)
-		ASCIIDOC7=
 		AC_MSG_RESULT([${asciidoc_version} (unknown)])
 		;;
 	esac
 fi
-AC_SUBST(ASCIIDOC7)
 
 
 ## Checks for libraries.
-- 
1.7.11.rc0.12.g6048c92

[PATCH 3/3] docs: drop antique comment from Makefile

[Jeff King]

This comment warns about a bug in asciidoc 6, and points to
a patch from 2005. Since we don't even support versions of
asciidoc that old, we can safely get rid of the warning.

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/Makefile | 9 ---------
 1 file changed, 9 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 030e2c8..eb1b6ad 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -125,15 +125,6 @@ DEFAULT_EDITOR_SQ = $(subst ','\'',$(DEFAULT_EDITOR))
 ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)'
 endif
 
-#
-# Please note that there is a minor bug in asciidoc.
-# The version after 6.0.3 _will_ include the patch found here:
-#   http://marc.theaimsgroup.com/?l=git&m=111558757202243&w=2
-#
-# Until that version is released you may have to apply the patch
-# yourself - yes, all 6 characters of it!
-#
-
 QUIET_SUBDIR0  = +$(MAKE) -C # space to separate -C and subdir
 QUIET_SUBDIR1  =
 
-- 
1.7.11.rc0.12.g6048c92