{"thread":{"id":"7945","subject":"[PATCH] Makefile: use --unsafe option under Cygwin with asciidoc","startedAt":"2007-05-02T11:49:58Z","lastAt":"2007-05-05T09:06:06Z","messageCount":6,"participants":["Jari Aalto","Eric Blake","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"40892","messageId":"ejlze97d.fsf@cante.net","threadId":"7945","inReplyTo":null,"subject":"[PATCH] Makefile: use --unsafe option under Cygwin with asciidoc","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2007-05-02T11:49:58Z","receivedAt":"2007-05-02T11:49:58Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"New: variable ASCIIDOC_FLAGS was introduced. It was also added to two\nnew targets. The old ASCIIDOC_EXTRA is set to --unsafe under Cygwin to\nignore asciidoc error about unsafe include.\n\nSigned-off-by: Jari Aalto \n---\n Documentation/Makefile | 18 +++++++++++++-----\n 1 files changed, 13 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 3f92783..399ff12 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -37,6 +37,14 @@ man7dir=$(mandir)/man7\n \n ASCIIDOC=asciidoc\n ASCIIDOC_EXTRA =\n+\n+ifneq (,$(CYGWIN))\n+# Ignore 'include' call errors\n+ASCIIDOC_EXTRA = --unsafe\n+endif\n+\n+ASCIIDOC_FLAGS += $(ASCIIDOC_EXTRA)\n+\n INSTALL?=install\n DOC_REF = origin/man\n \n@@ -112,7 +120,7 @@ clean:\n %.html : %.txt\n \trm -f $@+ $@\n \t$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \\\n-\t\t$(ASCIIDOC_EXTRA) -o - $< | \\\n+\t\t$(ASCIIDOC_FLAGS) -o - $< | \\\n \t\tsed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' >$@+\n \tmv $@+ $@\n \n@@ -122,12 +130,12 @@ clean:\n %.xml : %.txt\n \trm -f $@+ $@\n \t$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \\\n-\t\t$(ASCIIDOC_EXTRA) -o - $< | \\\n+\t\t$(ASCIIDOC_FLAGS) -o - $< | \\\n \t\tsed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' >$@+\n \tmv $@+ $@\n \n user-manual.xml: user-manual.txt user-manual.conf\n-\t$(ASCIIDOC) -b docbook -d book $<\n+\t$(ASCIIDOC) -b docbook -d book $(ASCIIDOC_FLAGS) $<\n \n XSLT = http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl\n XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css\n@@ -141,13 +149,13 @@ howto-index.txt: howto-index.sh $(wildcard howto/*.txt)\n \tmv $@+ $@\n \n $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n-\t$(ASCIIDOC) -b xhtml11 $*.txt\n+\t$(ASCIIDOC) -b xhtml11 $(ASCIIDOC_FLAGS) $*.txt\n \n WEBDOC_DEST = /pub/software/scm/git/docs\n \n $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt\n \trm -f $@+ $@\n-\tsed -e '1,/^$$/d' $< | $(ASCIIDOC) -b xhtml11 - >$@+\n+\tsed -e '1,/^$$/d' $< | $(ASCIIDOC) -b xhtml11 $(ASCIIDOC_FLAGS) - >$@+\n \tmv $@+ $@\n \n install-webdoc : html\n-- \n1.5.1.3\n"},{"id":"40896","messageId":"46388CBE.1080605@byu.net","threadId":"7945","inReplyTo":"ejlze97d.fsf@cante.net","subject":"Re: [PATCH] Makefile: use --unsafe option under Cygwin with asciidoc","fromName":"Eric Blake","fromEmail":"ebb9@byu.net","sentAt":"2007-05-02T13:06:06Z","receivedAt":"2007-05-02T13:06:06Z","isPatch":true,"sender":{"key":"eblake@redhat.com","avatar":"https://avatars.githubusercontent.com/u/32933908?v=4"},"body":"-----BEGIN PGP SIGNED MESSAGE-----\nHash: SHA1\n\nAccording to Jari Aalto on 5/2/2007 5:49 AM:\n> New: variable ASCIIDOC_FLAGS was introduced. It was also added to two\n> new targets. The old ASCIIDOC_EXTRA is set to --unsafe under Cygwin to\n> ignore asciidoc error about unsafe include.\n\nThis isn't just for cygwin, since it benefits any platform where the\ninstalled asciidoc is 8.1 or better (asciidoc is currently at 8.2.1 if you\nbuild the from tarballs).\n\n- --\nDon't work too hard, make some time for fun as well!\n\nEric Blake ebb9@byu.net\n-----BEGIN PGP SIGNATURE-----\nVersion: GnuPG v1.4.5 (Cygwin)\nComment: Public key at home.comcast.net/~ericblake/eblake.gpg\nComment: Using GnuPG with Mozilla - http://enigmail.mozdev.org\n\niD8DBQFGOIy+84KuGfSFAYARAo/XAKCuKOXb7cYzPL0AU4oiz5VbS54mtwCfVzX/\nbTMHegP6uvmaFZB5pKL5Dxo=\n=QYTe\n-----END PGP SIGNATURE-----\n"},{"id":"40903","messageId":"647bdywr.fsf@cante.net","threadId":"7945","inReplyTo":"46388CBE.1080605@byu.net","subject":"Re: [PATCH] Makefile: use --unsafe option under Cygwin with asciidoc","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2007-05-02T15:32:20Z","receivedAt":"2007-05-02T15:32:20Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Eric Blake writes:\n\n> According to Jari Aalto on 5/2/2007 5:49 AM:\n>\n>> New: variable ASCIIDOC_FLAGS was introduced. It was also added to two\n>> new targets. The old ASCIIDOC_EXTRA is set to --unsafe under Cygwin to\n>> ignore asciidoc error about unsafe include.\n>\n> This isn't just for cygwin, since it benefits any platform where the\n> installed asciidoc is 8.1 or better (asciidoc is currently at 8.2.1 if you\n> build the from tarballs).\n\nI thought this was Cygwin issue only. Should --unsafe be\nunconditionally enable by default?\n\nJari\n"},{"id":"40913","messageId":"7vslaf4121.fsf@assigned-by-dhcp.cox.net","threadId":"7945","inReplyTo":"46388CBE.1080605@byu.net","subject":"Re: [PATCH] Makefile: use --unsafe option under Cygwin with asciidoc","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2007-05-02T16:56:06Z","receivedAt":"2007-05-02T16:56:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Blake writes:\n\n> According to Jari Aalto on 5/2/2007 5:49 AM:\n>> New: variable ASCIIDOC_FLAGS was introduced. It was also added to two\n>> new targets. The old ASCIIDOC_EXTRA is set to --unsafe under Cygwin to\n>> ignore asciidoc error about unsafe include.\n>\n> This isn't just for cygwin, since it benefits any platform where the\n> installed asciidoc is 8.1 or better (asciidoc is currently at 8.2.1 if you\n> build the from tarballs).\n\nWhat unsafe things do we include? Maybe _that_ is what should\nbe fixed?\n\nAlso the last time we checked (I cannot take credits for this\nwork -- see \"git show origin/todo:TODO\" and look for\n\"AsciiDoc\"), AsciiDoc 8 had backward compatibility problems, and\nyou needed to add some pragma in asciidoc.conf to make it\ncompatible with sources written for AsciiDoc 7 (i.e. our\ndocumentation). However, the pragma is not understood by older\nasciidoc (and worse, makes older ones abort, as far as I\nrecall), so we cannot just add the pragma and use either\nAsciiDoc 7 or 8 interchangeably.\n"},{"id":"41126","messageId":"7v7irnlmgo.fsf@assigned-by-dhcp.cox.net","threadId":"7945","inReplyTo":"7vslaf4121.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Makefile: use --unsafe option under Cygwin with asciidoc","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2007-05-05T08:10:47Z","receivedAt":"2007-05-05T08:10:47Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Eric Blake writes:\n>\n>> According to Jari Aalto on 5/2/2007 5:49 AM:\n>>> New: variable ASCIIDOC_FLAGS was introduced. It was also added to two\n>>> new targets. The old ASCIIDOC_EXTRA is set to --unsafe under Cygwin to\n>>> ignore asciidoc error about unsafe include.\n>>\n>> This isn't just for cygwin, since it benefits any platform where the\n>> installed asciidoc is 8.1 or better (asciidoc is currently at 8.2.1 if you\n>> build the from tarballs).\n\nI got curious and tried this myself.\n\n> What unsafe things do we include? Maybe _that_ is what should\n> be fixed?\n\nI couldn't trigger \"unsafe\" error.\n\n> Also the last time we checked (I cannot take credits for this\n> work -- see \"git show origin/todo:TODO\" and look for\n> \"AsciiDoc\"), AsciiDoc 8 had backward compatibility problems, and\n> you needed to add some pragma in asciidoc.conf to make it\n> compatible with sources written for AsciiDoc 7 (i.e. our\n> documentation).\n\nHere are randomly selected differences between the documentation\npages formatted with AsciiDoc 7 and 8.\n\n --- 7\t2007-05-05 01:06:39.000000000 -0700\n +++ 8\t2007-05-05 01:06:36.000000000 -0700\n @@ -1,33 +1,33 @@\n git\\-bundle will only package references that are shown by git\\-show\\-ref:\n -this includes heads, tags, and remote heads. References such as master~1 \n +this includes heads, tags, and remote heads. References such as master1\n cannot be packaged, but are perfectly suitable for defining the basis.\n More than one reference may be packaged, and more than one basis can be\n specified. The objects packaged are those not contained in the union of\n -the given bases. Each basis can be specified explicitly (e.g., ^master~10),\n +the given bases. Each basis can be specified explicitly (e.g., ^master10),\n or implicitly (e.g., master~10..master, master \\-\\-since=10.days.ago).\n\nNotice broken tilde.\n\n -After this three\\-way merge, the local modifications are _not_\n +After this three\\-way merge, the local modifications are \\fInot\\fR\n registered in your index file, so git diff would show you what changes\n you made since the tip of the new branch.\n\n -

which will simply _create_ the branch, but will not do anything further.\n +

which will simply create the branch, but will not do anything further.\n\nAsciiDoc 8 knows _emphasis_ which is nice.\n\n -Allow ~user notation to be used in requests. When specified with no\n -parameter, requests to git://host/~alice/foo is taken as a request to\n +Allow user notation to be used in requests. When specified with no\n +parameter, requests to git://host/alice/foo is taken as a request to\n access \\fIfoo\\fR repository in the home directory of user alice. If\n \\-\\-user\\-path=path is specified, the same request is taken as a\n request to access path/foo repository in the home directory of user\n alice.\n\nAgain, broken tilde.\n\n In the above example output, the function signature was changed from\n -both files (hence two \\- removals from both file1 and file2, plus ++\n -to mean one line that was added does not appear in either file1 nor\n +both files (hence two \\- removals from both file1 and file2, plus + to\n +mean one line that was added does not appear in either file1 nor\n file2). Also two other lines are the same from file1 but do not appear\n -in file2 (hence prefixed with +).\n +in file2 (hence prefixed with ).\n\nMissing plus (in manpage output).\n\n

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

\n +from file1 but do not appear in file2 (hence prefixed with ).

\n

When shown by git diff-tree -c, it compares the parents of a\n\nSame (in HTML output).\n\nI haven't dug into the list archive article I quoted yet (the\npointer is also found in TODO file in 'todo' branch) and haven't\ntried the backward compatibility pragma, but you can clearly see\nthat the above differences are simply unacceptable. They are\nnot insignificant cosmetic differences -- the most important\ntechinical details are being mangled, rendering the\ndocumentation useless. We _do_ need the backward compatiblity\nenabled in asciidoc.conf or somewhere.\n"},{"id":"41129","messageId":"7v3b2bk5c1.fsf@assigned-by-dhcp.cox.net","threadId":"7945","inReplyTo":"7v7irnlmgo.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Makefile: use --unsafe option under Cygwin with asciidoc","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2007-05-05T09:06:06Z","receivedAt":"2007-05-05T09:06:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> I haven't dug into the list archive article I quoted yet (the\n> pointer is also found in TODO file in 'todo' branch) and haven't\n> tried the backward compatibility pragma, but you can clearly see\n> that the above differences are simply unacceptable. They are\n> not insignificant cosmetic differences -- the most important\n> techinical details are being mangled, rendering the\n> documentation useless. We _do_ need the backward compatiblity\n> enabled in asciidoc.conf or somewhere.\n\nFor AsciiDoc 8, this is minimally necessary. I vaguely recalled\nthat this needs to be conditional on the actual version of\nasciidoc as AsciiDoc 7 did not like it, but I haven't tried it\nrecently.\n\n-- >8 snip >8 --\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex ad87736..28c33f0 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -32,7 +32,7 @@ man1dir=$(mandir)/man1\n man7dir=$(mandir)/man7\n # DESTDIR=\n \n-ASCIIDOC=asciidoc\n+ASCIIDOC = asciidoc -a asciidoc7compatible\n ASCIIDOC_EXTRA =\n INSTALL?=install\n DOC_REF = origin/man\n\n-- 8< snap 8< --\n\nThis seems to make the build-product from asciidoc 8.2.1 mostly\nequivalent to asciidoc 7, but there still is one troubling\ndifference I spotted.\n\n --- 7\t2007-05-05 01:56:18.000000000 -0700\n +++ 8\t2007-05-05 01:56:29.000000000 -0700\n @@ -2,6 +2,6 @@\n A suffix \\fI~\\fR to a revision parameter means the\n commit object that is the th generation grand\\-parent\n of the named commit object, following only the first parent.\n -I.e. rev~3 is equivalent to rev^^^ which is equivalent to\n -rev^1^1^1. See below for a illustration of the usage of this form.\n +I.e. rev~3 is equivalent to rev^ which is equivalent to\n +rev11^1. See below for a illustration of the usage of this form.\n .TP 3n\n\nAgain, this is an unacceptable breakage that makes this part of the\ndocumentation useless. However, this part of the documentation\nuses our own \"[attributes] caret=^\" to work around the bug/misfeature\nin AsciiDoc 7, so maybe this could be (and needs to be) worked\naround by conditionally adjusting that macro to the version of\nAsciiDoc.\n\nI do not think we can say the current documentation set can be\nformatted sanely with AsciiDoc 8. Although I can say with\nreasonable comfort level that the output with AsciiDoc 7 has\nbeen proofread by enough people already, I cannot say the same\nfor AsciiDoc 8.\n\nSomebody needs to do some homework to devise a compatibility\nstudy between two versions, as we would eventually need to\nsupport both versions (iow, make our documentation set\nformattable with either version) at the same time.\n\nWhile \"use --unsafe\" (I did not trigger any unsafe_error(), so\nit may not be an issue) and giving \"-a asciidoc7compatible\" at\nthe command line might be one part of that compatibility study,\nI do not think that is the end of it. Proofreading the output\nand making sure the technical details are not lost in formatting\nerrors is the most important part.\n"}]}