Re: [PATCH] Makefile: use --unsafe option under Cygwin with asciidoc

[Junio C Hamano <junkio@cox.net>]

Junio C Hamano <junkio@cox.net> writes:

> I haven't dug into the list archive article I quoted yet (the
> pointer is also found in TODO file in 'todo' branch) and haven't
> tried the backward compatibility pragma, but you can clearly see
> that the above differences are simply unacceptable.  They are
> not insignificant cosmetic differences -- the most important
> techinical details are being mangled, rendering the
> documentation useless.  We _do_ need the backward compatiblity
> enabled in asciidoc.conf or somewhere.

For AsciiDoc 8, this is minimally necessary.  I vaguely recalled
that this needs to be conditional on the actual version of
asciidoc as AsciiDoc 7 did not like it, but I haven't tried it
recently.

-- >8 snip >8 --
diff --git a/Documentation/Makefile b/Documentation/Makefile
index ad87736..28c33f0 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -32,7 +32,7 @@ man1dir=$(mandir)/man1
 man7dir=$(mandir)/man7
 # DESTDIR=
 
-ASCIIDOC=asciidoc
+ASCIIDOC = asciidoc -a asciidoc7compatible
 ASCIIDOC_EXTRA =
 INSTALL?=install
 DOC_REF = origin/man

-- 8< snap 8< --

This seems to make the build-product from asciidoc 8.2.1 mostly
equivalent to asciidoc 7, but there still is one troubling
difference I spotted.

    --- 7	2007-05-05 01:56:18.000000000 -0700
    +++ 8	2007-05-05 01:56:29.000000000 -0700
    @@ -2,6 +2,6 @@
     A suffix \fI~<n>\fR to a revision parameter means the
     commit object that is the <n>th generation grand\-parent
     of the named commit object, following only the first parent.
    -I.e. rev~3 is equivalent to rev^^^ which is equivalent to
    -rev^1^1^1. See below for a illustration of the usage of this form.
    +I.e. rev~3 is equivalent to rev^ which is equivalent to
    +rev11^1. See below for a illustration of the usage of this form.
     .TP 3n

Again, this is an unacceptable breakage that makes this part of the
documentation useless.  However, this part of the documentation
uses our own "[attributes] caret=^" to work around the bug/misfeature
in AsciiDoc 7, so maybe this could be (and needs to be) worked
around by conditionally adjusting that macro to the version of
AsciiDoc.

I do not think we can say the current documentation set can be
formatted sanely with AsciiDoc 8.  Although I can say with
reasonable comfort level that the output with AsciiDoc 7 has
been proofread by enough people already, I cannot say the same
for AsciiDoc 8.

Somebody needs to do some homework to devise a compatibility
study between two versions, as we would eventually need to
support both versions (iow, make our documentation set
formattable with either version) at the same time.

While "use --unsafe" (I did not trigger any unsafe_error(), so
it may not be an issue) and giving "-a asciidoc7compatible" at
the command line might be one part of that compatibility study,
I do not think that is the end of it.  Proofreading the output
and making sure the technical details are not lost in formatting
errors is the most important part.