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

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

[Jari Aalto]

New: variable ASCIIDOC_FLAGS was introduced. It was also added to two
new targets. The old ASCIIDOC_EXTRA is set to --unsafe under Cygwin to
ignore asciidoc error about unsafe include.

Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 Documentation/Makefile |   18 +++++++++++++-----
 1 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 3f92783..399ff12 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -37,6 +37,14 @@ man7dir=$(mandir)/man7
 
 ASCIIDOC=asciidoc
 ASCIIDOC_EXTRA =
+
+ifneq (,$(CYGWIN))
+# Ignore 'include' call errors
+ASCIIDOC_EXTRA = --unsafe
+endif
+
+ASCIIDOC_FLAGS += $(ASCIIDOC_EXTRA)
+
 INSTALL?=install
 DOC_REF = origin/man
 
@@ -112,7 +120,7 @@ clean:
 %.html : %.txt
 	rm -f $@+ $@
 	$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \
-		$(ASCIIDOC_EXTRA) -o - $< | \
+		$(ASCIIDOC_FLAGS) -o - $< | \
 		sed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' >$@+
 	mv $@+ $@
 
@@ -122,12 +130,12 @@ clean:
 %.xml : %.txt
 	rm -f $@+ $@
 	$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
-		$(ASCIIDOC_EXTRA) -o - $< | \
+		$(ASCIIDOC_FLAGS) -o - $< | \
 		sed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' >$@+
 	mv $@+ $@
 
 user-manual.xml: user-manual.txt user-manual.conf
-	$(ASCIIDOC) -b docbook -d book $<
+	$(ASCIIDOC) -b docbook -d book $(ASCIIDOC_FLAGS) $<
 
 XSLT = http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl
 XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css
@@ -141,13 +149,13 @@ howto-index.txt: howto-index.sh $(wildcard howto/*.txt)
 	mv $@+ $@
 
 $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
-	$(ASCIIDOC) -b xhtml11 $*.txt
+	$(ASCIIDOC) -b xhtml11 $(ASCIIDOC_FLAGS) $*.txt
 
 WEBDOC_DEST = /pub/software/scm/git/docs
 
 $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt
 	rm -f $@+ $@
-	sed -e '1,/^$$/d' $< | $(ASCIIDOC) -b xhtml11 - >$@+
+	sed -e '1,/^$$/d' $< | $(ASCIIDOC) -b xhtml11 $(ASCIIDOC_FLAGS) - >$@+
 	mv $@+ $@
 
 install-webdoc : html
-- 
1.5.1.3

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

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to Jari Aalto on 5/2/2007 5:49 AM:
> New: variable ASCIIDOC_FLAGS was introduced. It was also added to two
> new targets. The old ASCIIDOC_EXTRA is set to --unsafe under Cygwin to
> ignore asciidoc error about unsafe include.

This isn't just for cygwin, since it benefits any platform where the
installed asciidoc is 8.1 or better (asciidoc is currently at 8.2.1 if you
build the from tarballs).

- --
Don't work too hard, make some time for fun as well!

Eric Blake             ebb9@byu.net
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFGOIy+84KuGfSFAYARAo/XAKCuKOXb7cYzPL0AU4oiz5VbS54mtwCfVzX/
bTMHegP6uvmaFZB5pKL5Dxo=
=QYTe
-----END PGP SIGNATURE-----

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

[Jari Aalto]

Eric Blake <ebb9@byu.net> writes:

> According to Jari Aalto on 5/2/2007 5:49 AM:
>
>> New: variable ASCIIDOC_FLAGS was introduced. It was also added to two
>> new targets. The old ASCIIDOC_EXTRA is set to --unsafe under Cygwin to
>> ignore asciidoc error about unsafe include.
>
> This isn't just for cygwin, since it benefits any platform where the
> installed asciidoc is 8.1 or better (asciidoc is currently at 8.2.1 if you
> build the from tarballs).

I thought this was Cygwin issue only. Should --unsafe be
unconditionally enable by default?

Jari

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

[Junio C Hamano]

Eric Blake <ebb9@byu.net> writes:

> According to Jari Aalto on 5/2/2007 5:49 AM:
>> New: variable ASCIIDOC_FLAGS was introduced. It was also added to two
>> new targets. The old ASCIIDOC_EXTRA is set to --unsafe under Cygwin to
>> ignore asciidoc error about unsafe include.
>
> This isn't just for cygwin, since it benefits any platform where the
> installed asciidoc is 8.1 or better (asciidoc is currently at 8.2.1 if you
> build the from tarballs).

What unsafe things do we include?  Maybe _that_ is what should
be fixed?

Also the last time we checked (I cannot take credits for this
work -- see "git show origin/todo:TODO" and look for
"AsciiDoc"), AsciiDoc 8 had backward compatibility problems, and
you needed to add some pragma in asciidoc.conf to make it
compatible with sources written for AsciiDoc 7 (i.e. our
documentation).  However, the pragma is not understood by older
asciidoc (and worse, makes older ones abort, as far as I
recall), so we cannot just add the pragma and use either
AsciiDoc 7 or 8 interchangeably.

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

[Junio C Hamano]

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

> Eric Blake <ebb9@byu.net> writes:
>
>> According to Jari Aalto on 5/2/2007 5:49 AM:
>>> New: variable ASCIIDOC_FLAGS was introduced. It was also added to two
>>> new targets. The old ASCIIDOC_EXTRA is set to --unsafe under Cygwin to
>>> ignore asciidoc error about unsafe include.
>>
>> This isn't just for cygwin, since it benefits any platform where the
>> installed asciidoc is 8.1 or better (asciidoc is currently at 8.2.1 if you
>> build the from tarballs).

I got curious and tried this myself.

> What unsafe things do we include?  Maybe _that_ is what should
> be fixed?

I couldn't trigger "unsafe" error.

> Also the last time we checked (I cannot take credits for this
> work -- see "git show origin/todo:TODO" and look for
> "AsciiDoc"), AsciiDoc 8 had backward compatibility problems, and
> you needed to add some pragma in asciidoc.conf to make it
> compatible with sources written for AsciiDoc 7 (i.e. our
> documentation).

Here are randomly selected differences between the documentation
pages formatted with AsciiDoc 7 and 8.

        --- 7	2007-05-05 01:06:39.000000000 -0700
        +++ 8	2007-05-05 01:06:36.000000000 -0700
        @@ -1,33 +1,33 @@
         git\-bundle will only package references that are shown by git\-show\-ref:
        -this includes heads, tags, and remote heads. References such as master~1 
        +this includes heads, tags, and remote heads. References such as master1
         cannot be packaged, but are perfectly suitable for defining the basis.
         More than one reference may be packaged, and more than one basis can be
         specified. The objects packaged are those not contained in the union of
        -the given bases. Each basis can be specified explicitly (e.g., ^master~10),
        +the given bases. Each basis can be specified explicitly (e.g., ^master10),
         or implicitly (e.g., master~10..master, master \-\-since=10.days.ago).

Notice broken tilde.

        -After this three\-way merge, the local modifications are _not_
        +After this three\-way merge, the local modifications are \fInot\fR
         registered in your index file, so git diff would show you what changes
         you made since the tip of the new branch.

        -<p>which will simply _create_ the branch, but will not do anything further.
        +<p>which will simply <em>create</em> the branch, but will not do anything further.

AsciiDoc 8 knows _emphasis_ which is nice.

        -Allow ~user notation to be used in requests. When specified with no
        -parameter, requests to git://host/~alice/foo is taken as a request to
        +Allow user notation to be used in requests. When specified with no
        +parameter, requests to git://host/alice/foo is taken as a request to
         access \fIfoo\fR repository in the home directory of user alice. If
         \-\-user\-path=path is specified, the same request is taken as a
         request to access path/foo repository in the home directory of user
         alice.

Again, broken tilde.

         In the above example output, the function signature was changed from
        -both files (hence two \- removals from both file1 and file2, plus ++
        -to mean one line that was added does not appear in either file1 nor
        +both files (hence two \- removals from both file1 and file2, plus + to
        +mean one line that was added does not appear in either file1 nor
         file2). Also two other lines are the same from file1 but do not appear
        -in file2 (hence prefixed with +).
        +in file2 (hence prefixed with ).

Missing plus (in manpage output).

         <p>In the above example output, the function signature was changed
         from both files (hence two <tt>-</tt> removals from both file1 and
        -file2, plus <tt>++</tt> to mean one line that was added does not appear
        +file2, plus <tt><tt>+</tt> to mean one line that was added does not appear
         in either file1 nor file2).  Also two other lines are the same
        -from file1 but do not appear in file2 (hence prefixed with <tt> +</tt>).</p>
        +from file1 but do not appear in file2 (hence prefixed with <tt> </tt></tt>).</p>
         <p>When shown by <tt>git diff-tree -c</tt>, it compares the parents of a

Same (in HTML output).

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.

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

[Junio C Hamano]

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.