[RFT] Format our Documentation/ with both AsciiDoc 7 & 8

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 15, 2007, 06:34 UTC
Message-ID: <7vfy4t915f.fsf@assigned-by-dhcp.pobox.com>
In-Reply-To: <11810823561507-git-send-email-madcoder@debian.org>

It turns out that the attribute definition we have had for a long time to hide "^" character from AsciiDoc 7 was not honored by AsciiDoc 8 even under "-a asciidoc7compatible" mode.

Also the double colon at the end of definition list term needs to be attached to the term, without a whitespace. After this minimum fixups, AsciiDoc 8 (I used 8.2.1 on Debian) with compatibility mode seems to produce reasonably good results.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---

 * This is "Request for Test" to people who reported problems
   formatting our documentation with asciidoc 8.  To format with
   Asciidoc 8, you would need to say something like:

	$ make ASCIIDOC8=YesPlease doc

   I've compared the output generated with AsciiDoc 7.1.2
   without this patch, and generated with AscooDoc 7.1.2 and
   AsciiDoc 8.2.1 with this patch.  Aside from the expected
   obvious differences in:

   - embedded Git version string in manpage output
   - generation datestamp in HTML output
   - autogenerated anchor href="#id" and name="id" in HTML output

   the only differences I saw are:

   - _word_ is rendered in HTML as <em>word<em> in AsciiDoc 8,
     while it used to come out verbatim under AsciiDoc 7.  Nice.

   - HTML stylesheet is a bit different from AsciiDoc 8.
     Presumably an improvement.

 Documentation/Makefile                |    3 +++
 Documentation/asciidoc.conf           |    2 +-
 Documentation/git-cvsexportcommit.txt |    2 +-
 Makefile                              |    6 ++++++
 4 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 9cef480..4edf788 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -37,6 +37,9 @@ man7dir=$(mandir)/man7
 
 ASCIIDOC=asciidoc
 ASCIIDOC_EXTRA =
+ifdef ASCIIDOC8
+ASCIIDOC_EXTRA += -a asciidoc7compatible
+endif
 INSTALL?=install
 DOC_REF = origin/man
 
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 99302c5..c135b6e 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -8,7 +8,7 @@
 # the command.
 
 [attributes]
-caret=^
+caret=&#94;
 startsb=&#91;
 endsb=&#93;
 tilde=&#126;
diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt
index 827711c..6c423e3 100644
--- a/Documentation/git-cvsexportcommit.txt
+++ b/Documentation/git-cvsexportcommit.txt
@@ -76,7 +76,7 @@ $ git-cvsexportcommit -v <commit-sha1>
 $ cvs commit -F .mgs <files>
 ------------
 
-Merge pending patches into CVS automatically -- only if you really know what you are doing ::
+Merge pending patches into CVS automatically -- only if you really know what you are doing::
 +
 ------------
 $ export GIT_DIR=~/project/.git
diff --git a/Makefile b/Makefile
index a70277b..d3b70d2 100644
--- a/Makefile
+++ b/Makefile
@@ -107,6 +107,8 @@ all::
 # Define USE_STDEV below if you want git to care about the underlying device
 # change being considered an inode change from the update-cache perspective.
 #
+# Define ASCIIDOC8 if you want to format documentation with AsciiDoc 8
+#
 # Define NO_PERL_MAKEMAKER if you cannot use Makefiles generated by perl's
 # MakeMaker (e.g. using ActiveState under Cygwin).
 #
@@ -684,6 +686,10 @@ ifndef V
 endif
 endif
 
+ifdef ASCIIDOC8
+	export ASCIIDOC8
+endif
+
 # Shell quote (do not use $(call) to accommodate ancient setups);
 
 SHA1_HEADER_SQ = $(subst ','\'',$(SHA1_HEADER))

-- 
1.5.2.1.280.g38570