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

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.