Documentation: rename docbook-xsl-172 attribute to git-asciidoc-no-roff

It seems that the ability to use raw roff codes in asciidoc.conf
was eliminated by docbook-xsl 1.72.0 _and later_. Unlike the
1.72.0-specific XSLT problem, this behavior was not reverted in
later releases.

This patch aims to make it clear that the affected asciidoc
attribute (flag) can be reasonably used with docbook-xsl versions
other than 1.72.0.

Also, document which make variables should be set for various
versions of asciidoc and docbook-xsl.

Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0.

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

diff --git a/Documentation/Makefile b/Documentation/Makefile
index e1562e351cc7e8fed63133a73dcb6a011a9d6ff2..d71760b8077ce68a02fd3fe0675cc43c758a5d8b 100644 (file)
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -59,12 +59,39 @@ endif
 -include ../config.mak.autogen
 -include ../config.mak
 
 -include ../config.mak.autogen
 -include ../config.mak
 

+#
+# For asciidoc ...
+#      -7.1.2, no extra settings are needed.
+#      8.0-,   set ASCIIDOC8.
+#
+
+#
+# For docbook-xsl ...
+#      -1.68.1,        set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0)
+#      1.69.0-1.71.1,  no extra settings are needed?
+#      1.72.0,         set DOCBOOK_XSL_172.
+#      1.73.0-,        set ASCIIDOC_NO_ROFF
+#
+
+#
+# If you had been using DOCBOOK_XSL_172 in an attempt to get rid
+# of 'the ".ft C" problem' in your generated manpages, and you
+# instead ended up with weird characters around callouts, try
+# using ASCIIDOC_NO_ROFF instead (it works fine with ASCIIDOC8).
+#
+

 ifdef ASCIIDOC8
 ASCIIDOC_EXTRA += -a asciidoc7compatible
 endif
 ifdef DOCBOOK_XSL_172
 ifdef ASCIIDOC8
 ASCIIDOC_EXTRA += -a asciidoc7compatible
 endif
 ifdef DOCBOOK_XSL_172

-ASCIIDOC_EXTRA += -a docbook-xsl-172
+ASCIIDOC_EXTRA += -a git-asciidoc-no-roff

 MANPAGE_XSL = manpage-1.72.xsl
 MANPAGE_XSL = manpage-1.72.xsl

+else
+       ifdef ASCIIDOC_NO_ROFF
+       # docbook-xsl after 1.72 needs the regular XSL, but will not
+       # pass-thru raw roff codes from asciidoc.conf, so turn them off.
+       ASCIIDOC_EXTRA += -a git-asciidoc-no-roff
+       endif

 endif
 
 #
 endif
 
 #

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 1e735df3bb5ba15b7f088442439e48a99ca85dbd..ce1b1755aedd419223c0076fae0cf426ab970e87 100644 (file)
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -27,7 +27,7 @@ ifdef::backend-docbook[]
 endif::backend-docbook[]
 
 ifdef::backend-docbook[]
 endif::backend-docbook[]
 
 ifdef::backend-docbook[]

-ifndef::docbook-xsl-172[]
+ifndef::git-asciidoc-no-roff[]

 # "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
 # v1.72 breaks with this because it replaces dots not in roff requests.
 [listingblock]
 # "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
 # v1.72 breaks with this because it replaces dots not in roff requests.
 [listingblock]


@@ -42,9 +42,9 @@ ifdef::doctype-manpage[]
 endif::doctype-manpage[]
 </literallayout>
 {title#}</example>
 endif::doctype-manpage[]
 </literallayout>
 {title#}</example>

-endif::docbook-xsl-172[]
+endif::git-asciidoc-no-roff[]

 
 

-ifdef::docbook-xsl-172[]
+ifdef::git-asciidoc-no-roff[]

 ifdef::doctype-manpage[]
 # The following two small workarounds insert a simple paragraph after screen
 [listingblock]
 ifdef::doctype-manpage[]
 # The following two small workarounds insert a simple paragraph after screen
 [listingblock]


@@ -62,7 +62,7 @@ ifdef::doctype-manpage[]
 </literallayout><simpara></simpara>
 {title#}</para></formalpara>
 endif::doctype-manpage[]
 </literallayout><simpara></simpara>
 {title#}</para></formalpara>
 endif::doctype-manpage[]

-endif::docbook-xsl-172[]
+endif::git-asciidoc-no-roff[]

 endif::backend-docbook[]
 
 ifdef::doctype-manpage[]
 endif::backend-docbook[]
 
 ifdef::doctype-manpage[]